Pagination

List endpoints return results one page at a time using cursor-based pagination. Each request takes a limit and an optional cursor. Each response returns that page in data, along with a has_more flag and the next_cursor you pass back to fetch the following page.

The request

Two query parameters control paging:

Parameter	Type	Default	Description
limit	integer	20	Items per page. Maximum 100; a higher value returns a 422 VALIDATION_ERROR.
cursor	string	n/a	The next_cursor from a previous response. Omit it to fetch the first page.

The response

Every list response has the same shape:

{
  "data": [],
  "has_more": true,
  "next_cursor": "eyJjI..."
}

Field	Type	Description
data	array	The current page of results.
has_more	boolean	true when more results exist beyond this page.
next_cursor	string | null	Opaque token to pass as cursor for the next page. null on the last page.

Example: iterating through your targets

List every target by following next_cursor until has_more is false:

Fetch the first page

Call the endpoint without a cursor. Use limit to set the page size:

Request

curl "https://spectral.principled.app/api/v1/targets?limit=2" \
     -H "Authorization: Bearer ak_****"

has_more is true, so there is another page, and next_cursor is the token to reach it:

Response

{
  "data": [
    {
      "id": "6a2ad...",
      "name": "Support Assistant",
      "description": "Customer support assistant for AcmeShip, a parcel delivery service...",
      "type": "ui",
      "created_at": "2026-06-11T16:06:03Z",
      "updated_at": "2026-06-11T16:06:03Z"
    },
    {
      "id": "b4f1c...",
      "name": "Billing Assistant",
      "description": "Billing and subscription assistant for AcmeShip account holders...",
      "type": "ui",
      "created_at": "2026-06-11T15:56:29Z",
      "updated_at": "2026-06-11T15:56:29Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjI..."
}

Fetch the next page

Pass next_cursor back as the cursor parameter, then repeat until has_more is false:

Request

CURSOR="eyJjI..."

curl "https://spectral.principled.app/api/v1/targets?limit=2&cursor=${CURSOR}" \
     -H "Authorization: Bearer ak_****"