Lists: limit and cursor
Cursors are opaque: pass them back exactly as you received them, and do not
parse, construct or store them long term. A cursor is bound to the query that
produced it, so keep the other filters the same while you page.
nextCursor is null, not when a page comes back empty. Some lists
filter by visibility after reading — for example, other members’ private
projects — so a page can be empty while more results remain.
These endpoints use cursor and nextCursor:
Other list endpoints return one bounded page controlled by
limit; their
reference pages say so.
Transcript words: wordCursor
GET /v1/projects/{projectId}/transcript pages the words of a composition’s
transcript rather than a list of items. wordLimit (default 1000, at most
2000) caps the words across all sources on one page; every source is listed on
every page with its wordCount, so merge the pages’ words by assetId.
Follow wordsNextCursor by sending it back as wordCursor, until it is
null.
A wordCursor is bound to the transcript it paged. If the composition changes
between pages (an edit, a new source or transcript), the next page answers
409 conflict with details.reason stale_cursor: discard the pages you
have and read again from the first page.
Ordered streams: after
A few endpoints return an ordered sequence you consume from the start and resume
later. For these, after is the last position you have already processed,
and the response tells you where to continue.
Persist the position with your own state. After a crash or a dropped WebSocket,
resume from it and you will not miss or repeat an event.
Deprecated parameters
Earlier spellings still work, so existing integrations keep running, but new code should usecursor:
The API reference marks these parameters as deprecated. See
Versioning for how deprecations work.
Hook search
GET /v1/hooks and GET /v1/hooks/stats search a bounded, changing sample of
recent content rather than a stable collection. They page with offset and
return nextOffset, which is null at the end of the sample.