Xpoz REST API

The Xpoz REST API exposes the same social media data layer as the MCP server and the SDKs through ordinary HTTPS requests. Use it when your stack has no SDK, when you want to call Xpoz from a serverless function or a shell script, or when you prefer to work directly with JSON. Base URL: https://api.xpoz.ai

Endpoint reference

Every endpoint with parameters, responses, and an interactive request builder, generated from the live OpenAPI spec.

Swagger UI

The same spec rendered by Swagger, served by the API itself.

OpenAPI spec (JSON)

Import into Postman, Insomnia, or a code generator.

OpenAPI spec (YAML)

The same document in YAML.

Endpoint families

Family	Path prefix	Auth	Metered
Live data	`/api/data/{platform}/.../live`	Access key	Yes
Operations	`/api/data/operations/{id}`	Access key	No
Account, billing, crawl settings	`/api/tokens`, `/api/plan`, `/api/usage`, `/api/crawl/...`, `/api/stripe/...`	Dashboard session	No
System status	`/api/status`, `/api/status/history`	None	No
Platform	`/health`, `/metrics`, `/openapi.json`	None	No

Live data endpoints fetch from the platform on demand and return one page plus a cursor. See Pagination. Account, billing, and crawl settings endpoints are the ones the Xpoz dashboard uses and are documented for completeness.

First request

Search Twitter/X for recent posts about a topic. Get a free access key from xpoz.ai/get-token.

curl -G "https://api.xpoz.ai/api/data/twitter/posts/live" \
  -H "Authorization: Bearer $XPOZ_API_KEY" \
  --data-urlencode "q=artificial intelligence" \
  --data-urlencode "fields=id,authorUsername,text,likeCount"

{
  "results": [
    {
      "id": "1973412345678901234",
      "authorUsername": "example",
      "text": "...",
      "likeCount": 42
    }
  ],
  "count": 20,
  "dataSource": "live",
  "has_more": true,
  "next_page_cursor": "DAACCgABG..."
}

Pass next_page_cursor back as cursor to fetch the next page.

Common query parameters

Most data endpoints accept the same options:

Parameter	Purpose
`q`	Search query using the query syntax
`fields`	Comma-separated list of attributes to return. See field selection
`since`, `until`	Inclusive date bounds, `YYYY-MM-DD`
`cursor`	Opaque cursor from the previous page

The exact parameters and allowed field names for each endpoint are listed on its reference page.

Errors

Status	Meaning
`400`	Validation failed, for example an empty search query or an invalid parameter.
`401`	Missing or invalid credentials.
`402`	The request is blocked by plan limits.
`403`	The endpoint is not available for this access key.
`404`	The post, user, or operation does not exist or has expired.
`500`	The request could not be fulfilled. Retry after a short pause.

Error bodies are JSON. Each endpoint’s reference page lists the exact statuses it returns.

Same data, other interfaces

The REST API, the MCP server, the SDKs, and the CLI all read the same data and meter the same credits. The SDKs’ live methods call these endpoints under the hood. Pick whichever fits your runtime; see how to access Xpoz.

Endpoint reference

Swagger UI

OpenAPI spec (JSON)

OpenAPI spec (YAML)

​Endpoint families

​First request

​Common query parameters

​Errors

​Same data, other interfaces

Endpoint families

First request

Common query parameters

Errors

Same data, other interfaces