Platform charges
Posting to X is billed on top of your plan, per call, at X's price plus
20%. X charges for every API call it serves, and a flat monthly price cannot
absorb a cost that depends entirely on how much you post. The charge is metered
on your subscription and appears on your invoice; GET /v1/usage shows it as
it accrues.
The charges are the organisation's bill, so GET /v1/usage shows them only to
a key whose creator may manage the organisation's billing. For any other key
platform_charges is null; the plan, its allowances and this month's use are
there either way.
We charge only for calls X accepted: a failed post costs nothing. We do not poll X for comments or DMs on your behalf, so you are never billed for a read you did not ask for.
The other networks cost nothing per call and are not billed this way.
Operations
GET /v1/usage
Read plan usage
Scope social:read.
The organisation's plan, its allowances, this month's use, and the platform charges billed
on top. The charges are the organisation's bill, so they are shown only when the person who
created the key may manage billing; for everybody else platform_charges is null.
Answers
| Status | Body | |
|---|---|---|
| 200 | Usage |
Usage. |
| 401 | ErrorEnvelope |
UNAUTHORIZED: no key, or one that is malformed, unknown or revoked. It never says which. |
| 403 | ErrorEnvelope |
INSUFFICIENT_SCOPE: the key lacks this operation's scope. Or ORGANISATION_SUSPENDED: the key's organisation is suspended. Never about another workspace's object, which is 404. |
| 429 | ErrorEnvelope |
RATE_LIMITED: too many requests. Wait for Retry-After seconds. |
| 500 | ErrorEnvelope |
INTERNAL_ERROR: ours. Safe to retry; send the same Idempotency-Key on a POST. |
Shapes
The objects these operations send and answer.
Network
One of: instagram, facebook, threads, bluesky, x, tiktok, linkedin, youtube, pinterest.
Usage
| Field | Type | |
|---|---|---|
plan |
string |
(required) |
period_start |
date |
(required) |
limits |
object |
Each limit by name, such as posts_per_month: the number that applies to your organisation right now, including any we have raised for it. Besides the allowances it carries the field sizes and ceilings a write is held to (page_title_chars, page_bio_chars, link_label_chars, contact_note_chars, social_icons_per_page, links_per_page, webhook_endpoints) and the hourly budgets (api_pages_created_per_hour, api_messages_per_hour, thread_messages_per_hour). AI is two allowances: ai_credits_per_month, one credit per AI draft (paid plans; 0 on Free), spent first, then ai_credits_per_day, where 1 credit is 10 tokens of what the AI reads and writes (3,000 on Free, about 70 for a reply draft); and ai_requests_per_minute drafts in any 60 seconds. (required) |
usage |
object |
This month's use, by allowance name (ai_credits counts this month's AI drafts), and ai_credits_today: today's AI credits, by UTC date, against ai_credits_per_day. They reset at midnight UTC and what is left is not carried over. (required) |
social_accounts |
integer |
(required) |
networks |
Network[] |
(required) |
platform_charges |
object | null |
This month's per-call charges billed on top of the plan, in thousandths of a US dollar. null unless the person who created the key may manage the organisation's billing: the charges are the organisation's bill, not the workspace's. (required) |