Pagination and envelopes | Siftsy Analyst API

Success

{ "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.

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 is a host path that already includes the prefix: /analyst/v1/analyses/an_….

Do not prepend /analyst/v1 to comments.path 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.

Errors

{ "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. Comment routes accept analysis bucket filters on the sample — see 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.