Pagination and filters

Cursor pagination

The lists of orders, sent messages, publications, fans and webhook delivery failures return one page at a time.

{
  "data": [{ "id": "…" }, { "id": "…" }],
  "next_cursor": "m_uR9U7Cvx7ZYe2d6jMuw45_ZHCGYC0HhU1c_rxLLMZ0eZ_gVQnv5hZ8-nsnCt2Pqk3ayA"
}

To read the next page, send the same request with cursor set to the next_cursor you received. A null cursor means you reached the last page.

curl "https://api.fansquare.so/v1/orders?limit=200&cursor=m_uR9U7Cvx7ZYe2d6jMuw45_ZHCGYC0HhU1c_rxLLMZ0eZ_gVQnv5hZ8-nsnCt2Pqk3ayA" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste"

• limit sets the page size, from 1 to 200, 50 by default (1 to 100 for webhook delivery failures).

• Cursors are opaque and encrypted: read them from a response, never build one. A cursor that was altered or not issued by the API returns 400 invalid_cursor.

• A cursor holds a position in the list, not your filters: send the same filters with every page.

Creators, employees, tags and webhook endpoints come in a single response, without next_cursor. Pending AI requests come oldest first, up to limit, without a cursor: acknowledge them to reach the next ones.

Filters

A filter that selects a subset is always plural and takes a comma-separated list, even for a single value.

?creator_ids=q7Ln2VbX9eKp4RtZ1wYc
?order_types=tip,push

• A list holds at most 50 values.

• An empty list (?creator_ids=) is a 400, never "everything".

Date ranges

The lists of orders and sent messages, and the delivery counters of a webhook endpoint, take start (inclusive) and end (exclusive) as ISO 8601 instants, such as 2026-10-01T00:00:00Z.

The analytics endpoints count whole days instead:

• start is the first day and end the last day, both included: start=2026-10-01&end=2026-10-31 covers all of October.

• Days are read in timezone, an IANA name such as Europe/Paris, and in UTC when it is omitted. Abbreviations such as CET are refused.

• A full date and time is accepted too: it stands for the day it falls on in timezone.

• A day that does not exist (2026-02-30), an end before start or a window longer than the endpoint allows returns 400 validation_failed. Each endpoint page gives its maximum window.

Unknown parameters

An endpoint that takes query parameters (the paginated lists, pending AI requests, analytics, webhook delivery failures and counters) answers 400 validation_failed to a parameter it does not know. A typo such as ?creator_id= (singular) fails loudly instead of being ignored and returning unfiltered results.

An endpoint without query parameters, such as GET /v1/creators, ignores any you send: GET /v1/creators?creator_ids=… still returns every creator the key covers.