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.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 · 5 surfaces
/docs/api-referenceEndpoint referenceLive /v1 read endpoints, parameters, response shapes, credit costs, and the /2 Basic Reads mapping./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.
Choose 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.
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.