> ## 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.

# List tweet monitors & metrics, X (Twitter) API docs

> List up to 10,000 post monitors a page with each post, author, event types, active state & 6 metrics with gains since tracking began. Listing monitors is free.

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

`GET https://xquik.com/api/v1/monitors/posts`

List every post monitor on your account. Each row holds the post, its author,
its event types & its 6 metrics. Each metric shows its current value & its gain
since tracking began.

**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?limit=50" \
  -H "x-api-key: xq_YOUR_KEY_HERE" |
  jq -c '.monitors[] | {
    post_monitor_id: .id,
    post_url: .postUrl,
    author_username: .authorUsername,
    is_active: .isActive,
    paused_reason: (.pausedReason // null),
    likes: .metrics.likes.current,
    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 response = await fetch("https://xquik.com/api/v1/monitors/posts?limit=50", {
  headers: { "x-api-key": "xq_YOUR_KEY_HERE" },
});
const page = await response.json();
for (const monitor of page.monitors) {
  const row = {
    post_monitor_id: monitor.id,
    post_url: monitor.postUrl,
    author_username: monitor.authorUsername,
    is_active: monitor.isActive,
    paused_reason: monitor.pausedReason ?? null,
    likes: monitor.metrics.likes.current,
    like_gain: monitor.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

response = requests.get(
    "https://xquik.com/api/v1/monitors/posts",
    headers={"x-api-key": "xq_YOUR_KEY_HERE"},
    params={"limit": 50},
)
page = response.json()
for monitor in page["monitors"]:
    row = {
        "post_monitor_id": monitor["id"],
        "post_url": monitor["postUrl"],
        "author_username": monitor["authorUsername"],
        "is_active": monitor["isActive"],
        "paused_reason": monitor.get("pausedReason"),
        "likes": monitor["metrics"]["likes"]["current"],
        "like_gain": monitor["metrics"]["likes"]["gain"],
    }
    print(json.dumps(row))
```

Each example prints 1 row per monitor. Pass `nextCursor` as `cursor` until
`hasMore` is `false`.

## Review every tracked post

| Question | Field | Next step |
| - | - | - |
| Which post is this? | `postUrl` & `authorUsername` | Open the post before you change the monitor. |
| Is it still billing? | `isActive` & `nextBillingAt` | Pause monitors nobody reads. |
| Did Xquik pause it? | `pausedReason` | Add credits, or delete monitors of deleted posts. |
| How far has engagement moved? | `metrics.*.gain` | Read hourly gains for the trend. |

A monitor paused with `insufficient_credits` resumes once you add credits &
turn it on. `x_post_deleted`, `x_post_protected` & `x_post_unavailable` mean
X stopped showing the post.

## 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). |

## Query parameters

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `limit` | `integer` | No | Monitors per page, from 1 to 10,000. Default `200`. |
| `cursor` | `string` | No | The previous page's `nextCursor`. The `after` alias also works. |

## Response

### 200 OK

| Field | Type | Description |
| - | - | - |
| `monitors` | `object[]` | Post monitors, each shaped like the [Get Post Monitor](https://docs.xquik.com/api-reference/monitors/get-post.md) response. |
| `total` | `number` | Post monitors on this page. |
| `hasMore` | `boolean` | `true` when another page exists. |
| `nextCursor` | `string` | Cursor for the next page. Present when `hasMore` is `true`. |

### 400 Invalid input

`limit` or `cursor` is invalid. Send a `nextCursor` value unchanged.

### 401 Unauthenticated

Missing or invalid API key.

### 429 Rate limited

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

> [!NOTE]
>
> **Related.** [Create Post Monitor](https://docs.xquik.com/api-reference/monitors/create-post.md), [Get Post Monitor](https://docs.xquik.com/api-reference/monitors/get-post.md), [Post Monitor Metrics](https://docs.xquik.com/api-reference/monitors/post-metrics.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"]}}
{
  "monitors": [],
  "total": 0,
  "hasMore": false
}
```

* **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." }`
* **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.