> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpoz.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Xpoz REST API

> Call Twitter/X, Instagram, Reddit, and TikTok data over plain HTTP from any language

The Xpoz REST API exposes the same social media data layer as the [MCP server](/mcp/overview) and the [SDKs](/sdks/typescript/quickstart) 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`

<CardGroup cols={2}>
  <Card title="Endpoint reference" icon="list" href="/api-reference/twitter-live/search-tweets-live">
    Every endpoint with parameters, responses, and an interactive request builder, generated from the live OpenAPI spec.
  </Card>

  <Card title="Swagger UI" icon="arrow-up-right-from-square" href="https://api.xpoz.ai/api-docs/">
    The same spec rendered by Swagger, served by the API itself.
  </Card>

  <Card title="OpenAPI spec (JSON)" icon="file-code" href="https://api.xpoz.ai/openapi.json">
    Import into Postman, Insomnia, or a code generator.
  </Card>

  <Card title="OpenAPI spec (YAML)" icon="file-lines" href="https://api.xpoz.ai/openapi.yaml">
    The same document in YAML.
  </Card>
</CardGroup>

## 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](/rest-api/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](https://xpoz.ai/get-token).

```bash theme={null}
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"
```

```json theme={null}
{
  "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](/guides/query-syntax) |
| `fields` | Comma-separated list of attributes to return. See [field selection](/mcp/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](/introduction#how-to-access-xpoz).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.