X statistics and credits: choose how often X numbers are read
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, Analytics and 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).
| 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. 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:
Terminal
JSON
| 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) 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.
Terminal
Terminal
The answer is the account, with its new x_statistics and source: "account":
JSON
(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:writeon 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.
Terminal
JSON
tweetshas one entry per tweet. A thread has one per part.credits_usedis 0.5 per tweet, plus 0.5 per tweet with a video or GIF. It is0when 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/:idshows them too. - It works whatever the setting, also with
posts: "off". - If X does not answer, you get
502 refresh_failedand 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.
Terminal
JSON
| 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, as always.
- No new X reads. No post checks and no follower counts. The numbers read before stay, each with its date (
collected_atin 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. They need no extra scope. Both use the usual envelope; data names the workspace and its X account:
JSON
| 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)andcredits.get()in every SDK. - MCP server:
set_x_statisticschanges the setting andupdate_post_analyticschecks a post now. See MCP server. - Analytics: how stored numbers are read is in Analytics.