> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hourly Twitter post metrics & engagement gains

> Get hourly views, likes, retweets, replies, quotes & bookmarks for 1 monitored X post. Each hour shows its closing value & gain. Read 1 to 720 hours for free.

**200**

```json theme={null}
{
  "hours": 1,
  "buckets": [
    {
      "at": "2026-10-22T11:00:00.000Z",
      "metrics": {
        "views": {
          "value": 541600,
          "gain": 500
        },
        "likes": {
          "value": 1890,
          "gain": 5
        },
        "retweets": {
          "value": 112,
          "gain": 0
        },
        "replies": {
          "value": 86,
          "gain": 1
        },
        "quotes": {
          "value": 87,
          "gain": 0
        }
      }
    }
  ]
}
```

**400**

```json theme={null}
{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}
```

**401**

```json theme={null}
{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}
```

**403**

```json theme={null}
{
  "error": "forbidden",
  "message": "This API key calls paid X read routes only, such as GET /api/v1/x/tweets/search. Create a Full access key at dashboard.xquik.com/account?tab=api-keys to call this route."
}
```

**404**

```json theme={null}
{
  "error": "not_found",
  "message": "Resource not found."
}
```

**429**

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}
```

> For the complete documentation index, see [llms.txt](/llms.txt).

Read a monitored post's metrics hour by hour. Each bucket holds every metric's
value at the hour's end & its gain over that hour.

**Free.** This endpoint does not consume credits.

```bash cURL theme={null}
curl "https://xquik.com/api/v1/monitors/posts/31/metrics?hours=24" \
  -H "x-api-key: xq_YOUR_KEY_HERE" |
  jq -c '.buckets[] | {
    hour: .at,
    views: .metrics.views.value,
    view_gain: .metrics.views.gain,
    likes: .metrics.likes.value,
    like_gain: .metrics.likes.gain
  }'
```

```javascript Node.js theme={null}
const monitorId = "31";
const response = await fetch(
  `https://xquik.com/api/v1/monitors/posts/${monitorId}/metrics?hours=24`,
  { headers: { "x-api-key": "xq_YOUR_KEY_HERE" } },
);
const history = await response.json();
for (const bucket of history.buckets) {
  const row = {
    hour: bucket.at,
    views: bucket.metrics.views.value,
    view_gain: bucket.metrics.views.gain,
    likes: bucket.metrics.likes.value,
    like_gain: bucket.metrics.likes.gain,
  };
  process.stdout.write(`${JSON.stringify(row)}\n`);
}
```

```python Python theme={null}
import json
import requests

monitor_id = "31"
response = requests.get(
    f"https://xquik.com/api/v1/monitors/posts/{monitor_id}/metrics",
    headers={"x-api-key": "xq_YOUR_KEY_HERE"},
    params={"hours": 24},
)
history = response.json()
for bucket in history["buckets"]:
    row = {
        "hour": bucket["at"],
        "views": bucket["metrics"]["views"]["value"],
        "view_gain": bucket["metrics"]["views"]["gain"],
        "likes": bucket["metrics"]["likes"]["value"],
        "like_gain": bucket["metrics"]["likes"]["gain"],
    }
    print(json.dumps(row))
```

## How do I chart a tweet's engagement over time?

Buckets come oldest first, 1 per hour. The last bucket is the current hour, so
its values keep moving.

Hours before tracking began carry the starting values with a gain of `0`.
Xquik keeps 30 days of history, which matches the 720-hour limit.

Sum the gains for a period's total. Use the last bucket's value for the current
count. A value & its gain are `null` when X shows no count, as for views on
old posts.

## Path parameters

**id** `string` *required*

The post monitor ID.

## Query parameters

**hours** `integer`

Hours to return, from 1 to 720. Default `12`.

## Headers

**x-api-key** `string` *required*

Your API key. Session cookie authentication is also supported. Generate a key from the [dashboard](https://dashboard.xquik.com/en/account?tab=api-keys).

## Response

### 200 OK

**hours** `integer`

Number of hours returned.

**buckets** `object[]`

Hourly buckets, oldest first.

**buckets\[].at** `string`

ISO 8601 start of the hour.

**buckets\[].metrics** `object`

`views`, `likes`, `retweets`, `replies`, `quotes` & `bookmarks`. Each holds `value` at the hour's
end & `gain` over that hour.

### 400 Invalid input

`hours` is not a whole number from 1 to 720.

### 401 Unauthenticated

Missing or invalid API key.

### 404 Not found

No post monitor has this ID on your account.

### 429 Rate limited

Too many requests. Wait for the `Retry-After` header before retrying.

> [!NOTE]
>
> **Related.** [Get Post Monitor](/api-reference/monitors/get-post.md), [List Post Monitors](/api-reference/monitors/list-posts.md), or [List Events](/api-reference/events/list.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.