Pagination and filtering

Cursor paging with exact page edges, filters that all run in SQL, and one sort parameter.

Cursor pagination

Cursors only. There is no offset paging. New replies arrive while you page, and an offset would skip or repeat rows.

Every list returns the same envelope:

{
  "object": "list",
  "data": [
    "…"
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0wNy0yN1QwOToxNDoyMi4wMDBafDk5MTIwNDE"
}

cursor=""
while :; do
  page=$(curl -sS "https://api.leadarc.io/v1/workspaces/airpay/leads?limit=100${cursor:+&cursor=$cursor}" \
    -H "Authorization: Bearer $LEADARC_API_KEY")
  echo "$page" | jq -c '.data[]'
  [ "$(echo "$page" | jq -r '.has_more')" = "true" ] || break
  cursor=$(echo "$page" | jq -r '.next_cursor')
done

No list returns a total count. Counting is too expensive. Page until has_more is false.

Filters

Every filter runs in the database. Nothing is filtered after loading, so a filtered page is never a partial answer.

An unknown query parameter is always 400 unsupported_filter, and the error names it. A typo like ?statuses=interested is reported instead of ignored.

GET /v1/workspaces/{ws}/leads filters:

Inside the app, INTERESTED and friends live on last_action, while booked and disqualified live on the feed axis backed by booked_at and disqualified_at. the app deliberately excludes DISQUALIFIED from its tag allow-list for that reason. An agent reading a docs table that lists seven lifecycle states will send all seven to one param, so the API accepts all seven on one param and routes them internally.

Note that DNC is surfaced as unsubscribed, because STATUS_META.DNC.label in the app is already "Unsubscribed". dnc is accepted as an alias on input and never returned.

updated_since is not mutually exclusive with cursor. Inside the app, fetchInboxRows treats cursor and since as exclusive with since winning silently, which makes "every lead that replied in June" impossible to express. The API allows a bounded window plus a cursor inside it, which is what a reconciliation job needs.

There is no q= full-text search. responses_index has responses_index_lead_email_idx and no trigram or tsvector index. A substring search over body_preview is a sequential scan on the largest table in the database. Exact email= is offered instead. Real search needs an index first, and that is a separate decision.

Sorting

One param, order, with two values: desc (default) and asc. It flips the endpoint's single fixed sort key. There is no sort_by.

Fixed sort keys: leads by (last_message_at, eb_reply_id). Meetings by (booked_at, id). Tasks by (due_date, id). Notes, templates, assets, sequences by (order_index, id) or (created_at, id) as noted per endpoint.

Expansions

?expand=a,b inlines related objects. Maximum three per request. More is 400 invalid_request.

expand=messages and expand=thread are not available on any list endpoint, at any limit. Building a thread calls buildLeadThreadMessages in the app, which on a cache miss makes up to 14 EmailBison round trips per lead (the anchor reply's conversation thread, up to MAX_SIBLINGS = 12 sibling threads, and the lead's /sent-emails). One hundred leads is up to 1,400 upstream calls in a single HTTP request. That would time out, exhaust the pool while writes queue behind it, and get the whole agency rate-limited by EmailBison, which breaks the Master Inbox for every human SDR. Threads are single-lead only, on GET /v1/workspaces/{ws}/leads/{lead}/messages.

Dates and times

updated_since, booked_before, from and to take a full date-time. task_due_before and due_after take YYYY-MM-DD and compare whole days, so no timezone shifts them.