> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.docs.siftsy.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.docs.siftsy.com/_mcp/server.

# Pagination and envelopes

> Cursor pages, response shape, and error bodies in the Siftsy Analyst API.

## Success

```json
{ "data": {}, "meta": {} }
```

List endpoints put rows in `data` (an array) and pagination in `meta`. Cursors are opaque — pass them back as `cursor`, do not parse them.

**Follow links with `url`.** Analyses and content jobs carry `url`, and every `comments` object carries `comments.url`. Both are absolute URLs on the host you called (for example `https://api.siftsy.app/analyst/v1/analyses/an_…/comments`), so you can request them as-is without joining paths.

If you do build URLs yourself, two kinds of path appear in responses:

* `comments.path` inside a payload is **relative to the base URL**: `https://api.siftsy.app/analyst/v1` + `/analyses/an_…/comments`.
* The `Location` header on `POST /analyses` and the content routes is a **host path** that already includes the prefix: `/analyst/v1/analyses/an_…`.

Do not prepend `/analyst/v1` to `comments.path` or `Location` a second time.

`limit` max is **100** (default 25) on post pages and on comment **samples**. Comment routes are evidence behind an analysis, not a full-thread export — prefer `source=notables`. See [Retrieving comments](/guides/core-concepts/retrieving-comments).

## Errors

```json
{ "error": { "message": "..." } }
```

| Status | Meaning                                                                                                                              |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| 401    | Missing or invalid API key                                                                                                           |
| 403    | Missing required scope                                                                                                               |
| 404    | Resource not in this key's team (fail closed)                                                                                        |
| 409    | `GET /analyses/{id}/comments` on an analysis that is not `ready` yet (`analysis_not_ready` / `analysis_failed`); honor `Retry-After` |
| 413    | Response over the per-response or daily byte cap                                                                                     |
| 429    | Per-key or daily transfer limit; honor `Retry-After`                                                                                 |

## Filters and sparse pages

`GET /posts` and `GET /collections/{collectionId}/posts` accept filters for link, account, platform, posted date, Siftsy score, and sentiment percentages — see [Filtering posts](/guides/core-concepts/filtering-posts). Comment routes accept analysis bucket filters on the **sample** — see [Retrieving comments](/guides/core-concepts/retrieving-comments). Filters are applied while filling the page, so pages stay close to `limit` instead of coming back empty while `hasMore` is still true. Send the same filters with each `cursor` request.