API contracts for read workflows.
Choose the right xfetch contract for your integration: /v1 workflow APIs for new builds, /2 for migration-friendly reads, plus OpenAPI and LLM-ready context for tooling.
Reference stack · 7 surfaces
/docs/api-referenceEndpoint referenceLive /v1 read endpoints, parameters, response shapes, credit costs, and the /2 Basic Reads mapping./docs/mcpHosted MCP for AI agentsHosted remote MCP setup for remote-MCP-compatible agents using normal xfetch read tools and credits./twitter-account-monitorAccount monitors & signed webhooksDashboard-configured Twitter account monitoring with Discord notifications and generic signed webhook payloads./openapi.jsonOpenAPI contractGenerated schemas for client tooling, schema inspection, and integration automation./llms-full.txtAgent-readable contextFull Markdown context for AI agents that need current endpoint layers, pricing rules, and examples./llms.txtCompact agent indexShort discovery file that points machines at the canonical contract resources./docs/x-api-compatible/2 compatibility subsetFocused official-compatible read paths for teams migrating familiar code.
Workflow paths
Choose a topic hub, then the endpoint that finishes the job.
Profiles & audience
Start with one profile snapshot, then traverse follower profiles or read the account timeline.Open Profiles & audience →Follower profiles · Account timelinesAI & MCP
Assemble normalized search, profile, timeline, and tweet inputs for agents through REST or the matching hosted MCP tools.Open AI & MCP →Hosted MCP setup · REST API referenceChoose the API family
Start with /v1; use /2 for migration.
/v1Recommended product APIStart new integrations here. Use xfetch names such as limit, next_token, and mode; read credits from meta.credits.View /v1 layers →/2Compatibility read layerUse this when migrating official-style read code. It keeps familiar paths and returns credit metadata in headers.View /2 docs →
Layer model
The API reference is organized by the job you need to finish.
Direct read endpoints for familiar search, user, tweet, graph, list, community, and trend data.
Use Basic Reads when you need one resource or one paginated collection with xfetch-owned /v1 parameters.Richer read endpoints that add normalized objects or alternate response modes around a core resource.
Use Enriched Reads when joined authors, profile objects, or richer timeline payloads remove client-side join work.Aggregated endpoints shaped around jobs such as profile intelligence and tweet context analysis.
Use Workflow APIs when one named response can replace several client-side calls and joins.Shared request rules
One auth model, visible credits, opaque pagination.
GET/v1/profiles/by-username/:username
recommendedRequest
GET /v1/profiles/by-username/jack Authorization: Bearer <api_key>
Response shape
{
"data": { "user": { ... }, "recent_tweets": [ ... ] },
"meta": { "credits": { "charged": 2 } }
}Auth
Authorization: Bearer <api_key>Customer API requests use bearer auth. Mint keys from the dashboard after Google sign-in.
Credits
meta.credits · x-credits-charged/v1 returns credit metadata in the response body. /2 keeps credit metadata in response headers.
Pagination
next_token · pagination_token/v1 uses meta.pagination.next_token and accepts next_token. /2 returns meta.next_token and accepts pagination_token.
Public errors
invalid_request · insufficient_creditsPublic errors use stable codes such as invalid_api_key, rate_limited, and service_unavailable. Internal details are not exposed.
Next step
Mint a key and make the first call.
Sign in with Google to mint a key and call any live /v1 or /2 read endpoint from the dashboard playground. New accounts receive 1,000 credits; failed validation, auth failures, insufficient credits, rate limits, and service-side failures are not charged.