Sync and backfill Inbox
Runs existing Inbox polling or a bounded X public-reply backfill. The inbound safety cap remains active.
Authorization
AuthorizationBearer <token>In header
Workspace API key kept server-side. Inbox requires the Basic plan or higher.
Query Params
inbox_scopestring
Required for API-key requests. Use managed_user for one app user or workspace with a creator-bound owner/admin key.
external_user_idOptionalstring
Required only for managed_user. Derive it from the authenticated app user on your server.
Request Body
x_backfillobject
Include this object to run a bounded X public-reply backfill. Omit it for the existing non-X Inbox sync.
x_backfill.account_idOptionalstring
Limit the operation to one eligible connected X account.
x_backfill.lookback_daysOptionalDefault: 7integer
1-7 days for X public-reply lookup.
x_backfill.max_itemsOptionalDefault: 20integer
1-500 resources per source and account.
x_backfill.include_repliesOptionalboolean
Fetch eligible mentions and replies.
x_backfill.confirmation_tokenOptionalstring
When the estimate exceeds the safe threshold, repeat the exact request with the returned one-time token before it expires.
Response Body
200
data.confirmation_requiredboolean
true when a second confirmed call is required before paid reads begin.
data.confirmation_tokenOptionalstring
Short-lived token bound to the exact account set, request, and estimate.
data.acceptedinteger
New items admitted to Inbox.
data.suppressedinteger
Items stopped by the inbound daily safety cap.
data.details[].stop_reasonOptionalstring
Includes x_monthly_usage_limit_exceeded, x_inbound_daily_cap_exceeded, or reconnect_required.
data.details[].missing_scopesOptionalstring[]
X permissions that require reconnect.
400
error.codestring
INBOX_SCOPE_REQUIRED when an API-key request omits inbox_scope.
plan_feature_not_available402
Inbox is unavailable below Basic.
validation_error400/409
The confirmation token is invalid, expired, already consumed, or no longer matches the frozen request.
not_found404
No eligible X account matched the request.
403
error.codestring
INBOX_SCOPE_REQUIRED when an API-key request omits inbox_scope.
plan_feature_not_available402
Inbox is unavailable below Basic.
validation_error400/409
The confirmation token is invalid, expired, already consumed, or no longer matches the frozen request.
not_found404
No eligible X account matched the request.
404
error.codestring
INBOX_SCOPE_REQUIRED when an API-key request omits inbox_scope.
plan_feature_not_available402
Inbox is unavailable below Basic.
validation_error400/409
The confirmation token is invalid, expired, already consumed, or no longer matches the frozen request.
not_found404
No eligible X account matched the request.
402
error.codestring
INBOX_SCOPE_REQUIRED when an API-key request omits inbox_scope.
plan_feature_not_available402
Inbox is unavailable below Basic.
validation_error400/409
The confirmation token is invalid, expired, already consumed, or no longer matches the frozen request.
not_found404
No eligible X account matched the request.
409
error.codestring
INBOX_SCOPE_REQUIRED when an API-key request omits inbox_scope.
plan_feature_not_available402
Inbox is unavailable below Basic.
validation_error400/409
The confirmation token is invalid, expired, already consumed, or no longer matches the frozen request.
not_found404
No eligible X account matched the request.