> ## 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 tweet monitor metrics, X (Twitter) API docs

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

> For the complete documentation index, see [llms.txt](https://docs.xquik.com/llms.txt).

`GET https://xquik.com/api/v1/monitors/posts/{id}/metrics`

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

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

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
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={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
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={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
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 730 days of history, which matches the 17,520-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.
Views on old posts are one example.

## Path parameters

| Path parameter | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The post monitor ID. |

## Query parameters

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `hours` | `integer` | No | Hours to return, from 1 to 17,520. Default `12`. |

## Headers

| Header | Type | Required | Description |
| - | - | - | - |
| `x-api-key` | `string` | Yes | 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

| Field | Type | Description |
| - | - | - |
| `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 17,520.

### 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](https://docs.xquik.com/api-reference/monitors/get-post.md), [List Post Monitors](https://docs.xquik.com/api-reference/monitors/list-posts.md), or [List Events](https://docs.xquik.com/api-reference/events/list.md).

## Response examples

### 200 example

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
{
  "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** `{ "error": "invalid_input", "message": "Invalid input. Check the request body." }`
* **401** `{ "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." }`
* **403** `{ "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." }`
* **404** `{ "error": "not_found", "message": "Resource not found." }`
* **429** `{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }`


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