OmniSocialsOmniSocials
DocumentationAPI reference
Help centerSupport
  • Documentation
  • API reference
Developers
  • Quickstart
  • API reference
  • SDKs
  • MCP server
  • CLI
For AI agents
  • Docs for AI agents
  • llms.txt
  • OpenAPI spec
  • Postman collection
Product
  • OmniSocials
  • Pricing
  • Changelog
  • Help center
Company
  • Support
  • Privacy policy
  • Terms of service

© 2026 OmniSocials

OmniSocials on GitHubOmniSocials on XOmniSocials on LinkedIn
Overview
Get started
SDKs
CLI
MCPDocs for AI agentsWebhooks
Guides
    PostsStoriesReelsCross-postingMediaAnalyticsX statistics and creditsPost tagsSocial inboxAutomations
Platforms
Integrations
Migrate
Plans and billing
GlossaryChangelogAPI reference
Guides

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.

EndpointWhat it doesScope
GET /accounts, GET /accounts/:idAn X account carries its setting in x_statisticsaccounts:read
PATCH /accounts/:idChange how often an X account is readaccounts:write (opt-in)
POST /analytics/posts/:id/refreshCheck the X numbers of one post now ("Update now")analytics:read
GET /creditsYour balance, this month's X statistics use and an estimate per accountcredits: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).

ReadX chargesCredits
One post check (each tweet of a thread counts)$0.0050.5
The video or GIF of a checked tweet$0.0050.5 more
One follower count of an X account$0.0101
Update now on a post$0.005 per tweet0.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.

ValueIn the appWhen a post is checked
full5 checksAbout 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
light2 checksAbout 5 hours after publishing and after day 7
offOffNever. 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.

ValueIn the appCredits a month
dailyDailyAbout 30
weeklyWeeklyAbout 4
offOff0

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:

TerminalTerminal
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 } } }
FieldMeaning
postsfull, light or off
followersdaily, weekly or off
sourceaccount when the setting was set on this account, default when it was never set
billingcredits: the reads use your organisation's credits
stateactive, paused (no credits left, see When credits run out) or off (both settings are off)
paused_reasoninsufficient_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.

TerminalTerminal
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" } }'
TerminalTerminal
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.

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

TerminalTerminal
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 } ] } } }
FieldMeaning
balanceWhole credits on the organisation's balance
auto_refill.enabledWhether auto-refill tops the balance up by itself
this_monthCredits 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.stateactive or paused, with paused_at
x_statistics.chargingfrom: the date reads started to cost credits (null while no date is set). active: whether that date has passed
x_statistics.pricesCredits per post check, per video or GIF, per follower count
x_statistics.this_monthThis month's reads: post checks, video or GIF reads, follower counts, Update now calls, and their credits
x_statistics.accountsEach 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_monthThe 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_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. 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" } }
EventWhendata.reason
x_statistics.pausedX statistics paused: no credits leftinsufficient_credits
x_statistics.resumedX statistics run again after credits came incredits_added

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

Scopes and permissions

ScopeGives
accounts:writePATCH /accounts/:id
credits:readGET /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

StatusCodeWhen
400validation_errorx_statistics is missing from the body or is not an object; a post id that is not a number
400invalid_valueposts or followers is not one of the values above
400not_supportedPATCH /accounts/:id on an account that is not X
402insufficient_creditsUpdate now: the balance does not cover the read
403insufficient_scopeThe key lacks accounts:write or credits:read
403insufficient_permissionThe 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
404not_foundThe account or the post is not in the key's workspace
409refresh_not_availableThe post has no published X tweet
429refresh_limit5 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
502refresh_failedX 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.
  • MCP server: set_x_statistics changes the setting and update_post_analytics checks a post now. See MCP server.
  • Analytics: how stored numbers are read is in Analytics.
Last modified on November 8, 2026
AnalyticsPost tags
On this page
  • Why X statistics cost credits
  • Prices
  • The choices
  • Read the setting
  • Change the setting
  • Check a post now (Update now)
  • Read your balance and use
  • When credits run out
  • Webhook events
  • Scopes and permissions
  • Errors
  • Other ways to use it
JSON
JSON
JSON
JSON
JSON