# X statistics and credits: choose how often X numbers are read

> Index of all OmniSocials docs pages: https://docs.omnisocials.com/llms.txt

X bills every read of a post's statistics. OmniSocials passes that price on as credits, at X's own rate, with no markup. You choose per X account how often its numbers are read, so you pay only for the checks you want.

Only X statistics work this way. The statistics of every other network stay part of your plan, and an X post without a link still costs nothing to publish.

| Endpoint | What it does | Scope |
| --- | --- | --- |
| `GET /accounts`, `GET /accounts/:id` | An X account carries its setting in `x_statistics` | `accounts:read` |
| `PATCH /accounts/:id` | Change how often an X account is read | `accounts:write` (opt-in) |
| `POST /analytics/posts/:id/refresh` | Check the X numbers of one post now ("Update now") | `analytics:read` |
| `GET /credits` | Your balance, this month's X statistics use and an estimate per account | `credits:read` (opt-in) |

Two webhook events tell you when X statistics pause and start again: `x_statistics.paused` and `x_statistics.resumed`. The full schemas are in the API reference under [Accounts](https://docs.omnisocials.com/api/accounts), [Analytics](https://docs.omnisocials.com/api/analytics) and [Credits](https://docs.omnisocials.com/api/credits).

## Why X statistics cost credits

X's API charges for each read. Reading the numbers of a post costs $0.005 (X bills a post once per UTC day), the video or GIF that comes with that read costs $0.005 more, and reading the follower count of an account costs $0.010. Until now OmniSocials paid for all of it. Now you decide how often your X numbers are read, and those reads use credits at X's price.

## Prices

1 credit is €0.01, counted as $0.01 of X's price list. You buy credits in the app under **Settings → Organisation → Billing → Credits** ([app.omnisocials.com/credits](https://app.omnisocials.com/credits)).

| Read | X charges | Credits |
| --- | --- | --- |
| One post check (each tweet of a thread counts) | $0.005 | 0.5 |
| The video or GIF of a checked tweet | $0.005 | 0.5 more |
| One follower count of an X account | $0.010 | 1 |
| Update now on a post | $0.005 per tweet | 0.5 per tweet, plus 0.5 per tweet with a video or GIF. Free when the post was already read that UTC day |

Photos add nothing: X gives no numbers for them, so a check does not ask for them.

Your balance holds whole credits. Half credits are added up and taken off in whole credits; an odd half waits for the next read.

An example. An account that posts 20 tweets a month without video, on 5 checks and with a daily follower count, uses about 43 credits for its posts and 30 for its followers: about 73 credits, or €0.73, a month. The same account on 2 checks with a weekly follower count uses about 24 credits. `GET /credits` gives this estimate for your own accounts, from their last 30 days.

Reads cost credits from the date in `x_statistics.charging.from` of [`GET /credits`](#read-your-balance-and-use). Before that date reads are counted, so you can see your use first, but nothing comes off your balance. Organisations that already used X got start credits once, so their balance covers about 3 months of their own X statistics.

## The choices

Each X account has two settings. A workspace has one X account, so the setting belongs to that workspace.

**Posts**: how often each post is checked.

| Value | In the app | When a post is checked |
| --- | --- | --- |
| `full` | 5 checks | About 5 hours after publishing, then after day 1, day 3 and day 7. After day 30 once more, only for a post that had 100 or more views at day 7 |
| `light` | 2 checks | About 5 hours after publishing and after day 7 |
| `off` | Off | Never. The numbers read before stay. Update now still works |

In our data an X post has 82% of its final views after a day and a half, and 98% after a week. Most views that come after day 7 are on posts with 100 or more views, so `full` checks only those once more.

**Followers**: how often the follower count is read.

| Value | In the app | Credits a month |
| --- | --- | --- |
| `daily` | Daily | About 30 |
| `weekly` | Weekly | About 4 |
| `off` | Off | 0 |

An X account you never set uses `full` and `daily`: the checks every X account had before this change. A change applies from the next check, also to posts that are already published. In the app you choose when you connect X, and you can change it later on the Credits page.

## Read the setting

Every X account in `GET /accounts` and `GET /accounts/:id` carries `x_statistics`:

```bash
curl https://api.omnisocials.com/v1/accounts/1234_x \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY"
```

```json
{
  "data": {
    "id": "1234_x",
    "platform": "x",
    "username": "yourbrand",
    "display_name": "Your Brand",
    "profile_picture": "https://pbs.twimg.com/profile_images/.../photo.jpg",
    "content_types": ["post"],
    "status": "active",
    "needs_reconnect": false,
    "pick_pending": false,
    "connected_at": "2026-03-02T10:14:00.000Z",
    "x_statistics": {
      "posts": "full",
      "followers": "daily",
      "source": "default",
      "billing": "credits",
      "state": "active",
      "paused_reason": null
    }
  }
}
```

| Field | Meaning |
| --- | --- |
| `posts` | `full`, `light` or `off` |
| `followers` | `daily`, `weekly` or `off` |
| `source` | `account` when the setting was set on this account, `default` when it was never set |
| `billing` | `credits`: the reads use your organisation's credits |
| `state` | `active`, `paused` (no credits left, see [When credits run out](#when-credits-run-out)) or `off` (both settings are off) |
| `paused_reason` | `insufficient_credits` while paused, otherwise `null` |

`x_statistics` is `null` in the rare case the setting cannot be read; the account list itself never fails on it.

## Change the setting

Send `x_statistics` with one key or both. A key you leave out keeps its value.

```bash
curl -X PATCH https://api.omnisocials.com/v1/accounts/1234_x \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "x_statistics": { "posts": "light" } }'
```

```bash
curl -X PATCH https://api.omnisocials.com/v1/accounts/1234_x \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "x_statistics": { "posts": "full", "followers": "weekly" } }'
```

The answer is the account, with its new `x_statistics` and `source: "account"`:

```json
{
  "data": {
    "id": "1234_x",
    "platform": "x",
    "x_statistics": {
      "posts": "light",
      "followers": "daily",
      "source": "account",
      "billing": "credits",
      "state": "active",
      "paused_reason": null
    }
  }
}
```

(Shortened: the answer carries every account field.)

Changing the setting changes what your organisation pays, so it needs two things:

- The opt-in scope `accounts:write` on the key (the **Credits and X statistics** switch when you create it).
- Billing rights (`manage_billing`) for the person who created the key, checked on every call. Owners and admins have them.

Only X accounts have this setting. A PATCH on any other account answers `400 not_supported`.

## Check a post now (Update now)

`POST /analytics/posts/:id/refresh` reads the X numbers of one published post now, outside its schedule. Use the OmniSocials post id, as in [`GET /analytics/posts/:id`](https://docs.omnisocials.com/analytics.md#get-analytics-for-one-post).

```bash
curl -X POST https://api.omnisocials.com/v1/analytics/posts/9123/refresh \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY"
```

```json
{
  "data": {
    "post_id": 9123,
    "tweets": [
      {
        "id": "1859000000000000000",
        "metrics": { "views": 3412, "likes": 41, "comments": 9, "reposts": 6 },
        "read_at": "2027-01-08T09:12:04.000Z"
      }
    ],
    "credits_used": 0.5,
    "read_at": "2027-01-08T09:12:04.000Z"
  }
}
```

- `tweets` has one entry per tweet. A thread has one per part.
- `credits_used` is 0.5 per tweet, plus 0.5 per tweet with a video or GIF. It is `0` when the post was already read that UTC day (X bills a post once a day, so a second check that day is free), and before the charging date.
- At most 5 reads of a post per UTC day (scheduled checks count too) and 100 Update now checks per organisation per UTC day. Past either limit the answer is `429 refresh_limit`.
- The new numbers are stored, so `GET /analytics/posts/:id` shows them too.
- It works whatever the setting, also with `posts: "off"`.
- If X does not answer, you get `502 refresh_failed` and nothing is charged. Try again in a few minutes.

## Read your balance and use

`GET /credits` returns your organisation's balance and its X statistics: the state, this month's reads and an estimate per X account.

```bash
curl https://api.omnisocials.com/v1/credits \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY"
```

```json
{
  "data": {
    "balance": 412,
    "auto_refill": { "enabled": false },
    "this_month": { "x_statistics": 31, "x_url_post": 40, "x_dm_send": 6 },
    "x_statistics": {
      "state": "active",
      "paused_at": null,
      "charging": { "active": true, "from": "2027-01-01T00:00:00.000Z" },
      "prices": { "post_read": 0.5, "media_read": 0.5, "follower_read": 1 },
      "total_credits_month": 72.9,
      "this_month": {
        "post_reads": 52,
        "media_reads": 6,
        "follower_reads": 8,
        "refreshes": 2,
        "credits": 37
      },
      "accounts": [
        {
          "account_id": "1234_x",
          "workspace_id": 1234,
          "handle": "@yourbrand",
          "posts": "full",
          "followers": "daily",
          "tweets_30d": 20,
          "credits_month": 72.9
        }
      ]
    }
  }
}
```

| Field | Meaning |
| --- | --- |
| `balance` | Whole credits on the organisation's balance |
| `auto_refill.enabled` | Whether auto-refill tops the balance up by itself |
| `this_month` | Credits used this calendar month (UTC), per reason: `x_statistics`, `x_url_post` (X link posts), `x_dm_send` (X DM replies) and others |
| `x_statistics.state` | `active` or `paused`, with `paused_at` |
| `x_statistics.charging` | `from`: the date reads started to cost credits (`null` while no date is set). `active`: whether that date has passed |
| `x_statistics.prices` | Credits per post check, per video or GIF, per follower count |
| `x_statistics.this_month` | This month's reads: post checks, video or GIF reads, follower counts, Update now calls, and their credits |
| `x_statistics.accounts` | Each X account with its setting, its tweets of the last 30 days (`tweets_30d`) and its estimate for a month (`credits_month`) |
| `x_statistics.total_credits_month` | The estimate for all X accounts together |

`GET /credits` needs the opt-in scope `credits:read` (the **Credits and X statistics** switch when you create the key) and billing rights (`manage_billing`) for the person who created the key. Credits are bought in the app; the API only reads them.

## When credits run out

When a read no longer fits in your balance, X statistics pause for the whole organisation:

- **Publishing does not stop.** Posts still go out on X. A post with a link still needs its own [20 credits](https://docs.omnisocials.com/platforms/x.md#link-posts-use-credits), as always.
- **No new X reads.** No post checks and no follower counts. The numbers read before stay, each with its date (`collected_at` in analytics).
- **Update now** answers `402 insufficient_credits`, unless the post was already read that UTC day (then it is free).
- **You are told once.** The people with billing rights get a notice in the app and an email, and your webhooks get `x_statistics.paused`, one per workspace with X.

Before that, when the balance covers less than 7 days of your own X statistics, those people get a warning in the app and by email.

After a top-up, an auto-refill or a credit grant, checks start again by themselves and your webhooks get `x_statistics.resumed`. A post that missed checks while paused gets one catch-up check, not one for every check it missed.

## Webhook events

Add `x_statistics.paused` and `x_statistics.resumed` to the `events` of a [webhook](https://docs.omnisocials.com/webhooks.md). They need no extra scope. Both use the usual envelope; `data` names the workspace and its X account:

```json
{
  "id": "3c0f9a51-7d2e-4b8a-9e1f-5a6b7c8d9e0f",
  "type": "x_statistics.paused",
  "created_at": "2027-02-14T06:00:12.000Z",
  "data": {
    "workspace_id": 1234,
    "account_id": "1234_x",
    "reason": "insufficient_credits"
  }
}
```

| Event | When | `data.reason` |
| --- | --- | --- |
| `x_statistics.paused` | X statistics paused: no credits left | `insufficient_credits` |
| `x_statistics.resumed` | X statistics run again after credits came in | `credits_added` |

An organisation with several X workspaces sends one event per workspace.

## Scopes and permissions

| Scope | Gives |
| --- | --- |
| `accounts:write` | `PATCH /accounts/:id` |
| `credits:read` | `GET /credits` |

Both are opt-in: one switch, **Credits and X statistics**, adds both when you create the key. A new key does not get them unless you switch it on, and existing keys never get them by themselves. Both also need billing rights (`manage_billing`) for the person who created the key, checked on every call. A key without the scope gets `403 insufficient_scope`; a key whose creator has no billing rights gets `403 insufficient_permission`.

`POST /analytics/posts/:id/refresh` needs only `analytics:read`, which every key has by default. It can use credits: at most 5 reads per post and 100 Update now checks per organisation per UTC day.

Through OAuth (an AI assistant signed in to the hosted MCP server), the role of the person who signed in counts instead of the scope: changing the setting needs billing rights there too (`403 insufficient_permission`).

## Errors

| Status | Code | When |
| --- | --- | --- |
| `400` | `validation_error` | `x_statistics` is missing from the body or is not an object; a post id that is not a number |
| `400` | `invalid_value` | `posts` or `followers` is not one of the values above |
| `400` | `not_supported` | `PATCH /accounts/:id` on an account that is not X |
| `402` | `insufficient_credits` | Update now: the balance does not cover the read |
| `403` | `insufficient_scope` | The key lacks `accounts:write` or `credits:read` |
| `403` | `insufficient_permission` | The key's creator (or, through OAuth, the person who signed in) has no billing rights. In a rare case the route itself answers `forbidden` for the same reason |
| `404` | `not_found` | The account or the post is not in the key's workspace |
| `409` | `refresh_not_available` | The post has no published X tweet |
| `429` | `refresh_limit` | 5 reads of this post today, or 100 Update now checks of the organisation today (UTC). This is not the rate limit: try again the next UTC day |
| `502` | `refresh_failed` | X did not answer. Nothing was charged. Try again in a few minutes |

Through the hosted MCP server, a refused Update now reads `x_feature_not_enabled`.

## Other ways to use it

- **SDKs**: `accounts.update(id, { x_statistics })`, `analytics.refreshPost(id)` and `credits.get()` in every [SDK](https://docs.omnisocials.com/sdks.md#x-statistics).
- **MCP server**: `set_x_statistics` changes the setting and `update_post_analytics` checks a post now. See [MCP server](https://docs.omnisocials.com/mcp-server.md).
- **Analytics**: how stored numbers are read is in [Analytics](https://docs.omnisocials.com/analytics.md#how-metrics-are-collected).
