Pagination - Synthetic API

A list route returns one page at a time, in this shape:

{
  "data": [
    { "id": "0199a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b", "type": "CASH", "amount": { "value": 10000, "currencyCode": "USD" } }
  ],
  "hasMore": true,
  "nextCursor": "v1.eyJpZCI6IjAxOTk...",
  "prevCursor": "v1.eyJpZCI6IjAxOTk..."
}

Field	Meaning
`data`	The records on this page. Each list’s order is stated in its API Reference description.
`hasMore`	Whether more records exist beyond this page in the direction you are reading.
`nextCursor`	Send it as `startingAfter` to read the page after this one. Absent when the page is empty.
`prevCursor`	Send it as `endingBefore` to read the page before this one. Absent when the page is empty.

Parameters

Parameter	Meaning
`limit`	Records per page, 1 to 100. Defaults to 50.
`startingAfter`	A `nextCursor` from a previous page.
`endingBefore`	A `prevCursor` from a previous page.
`orderBy`	Fields to sort by, when the list offers it, each written `field:ASC` or `field:DESC` and separated by commas. The API Reference lists each route’s sortable fields and its default order.

A request may carry startingAfter or endingBefore, not both. A list that is worked out on each read, such as QUERY /invoice-previews, always fits on one page. It returns the same shape with hasMore false and no cursors, and ignores limit and cursors if they are sent.

Reading a whole list

Request the first page with no cursor.
If hasMore is true, request the next page with startingAfter set to the nextCursor you received.
Repeat until hasMore is false.

curl "https://app.synthetic.ai/api/v1/payments?limit=100" \
  -H "Authorization: Bearer <key>"

curl "https://app.synthetic.ai/api/v1/payments?limit=100&startingAfter=<nextCursor>" \
  -H "Authorization: Bearer <key>"

Filters and order

A list route may accept filters, listed in the API Reference for that route. Boolean filters take the words true and false. A filter that takes several values takes them separated by commas, for example filter=FIRST,SECOND, and an empty one is the same as leaving it out. A query parameter the route does not take, such as a misspelled filter, returns 400 rather than a list that ignores it. A cursor is bound to the filters and the orderBy it was issued under. Sending it back with different filters or a different order returns 400 rather than a page that silently skips or repeats records. To change either, start again from the first page with no cursor. Cursors are opaque. Store and return them unchanged, and do not build them yourself.

​Parameters

​Reading a whole list

​Filters and order

Parameters

Reading a whole list

Filters and order