Pagination & filtering

:::warning Read this before building a list view No list endpoint paginates today. Every one returns the full set in a single response. On a large account, GET /users is a big response. :::

Today

Endpoint	Returns	Filters
GET /users	Every user the credential may see	None
GET /sms/lines	Every SMS-capable number the credential may see	None
GET /webhooks	Every subscription	type, enabled=true
GET /calls/{id}/recordings	Every recorded leg of one call	None — naturally bounded

Order is guaranteed on one endpoint only: GET /users is sorted by last name, then first name, then id. That makes diffing two responses meaningful. The others return storage order, which you should not depend on.

Filtering, where it exists

GET /webhooks takes two query parameters:

curl "…/webhooks?type=AccountSMS" -H "Authorization: Bearer $TB_KEY"
curl "…/webhooks?enabled=true"    -H "Authorization: Bearer $TB_KEY"

An absent parameter really is "no filter". An unknown type is a 400 rather than an empty result — you find out you typo'd instead of concluding there are no subscriptions.

:::caution enabled=false is not supported It returns 400 with "type": "unsupported". Only a positive filter can be expressed. To list the disabled subscriptions, omit enabled and filter the result yourself. :::

Writing a client that survives pagination arriving

Pagination will be added, and the responses are already shaped so that it can be without breaking you:

{ "data": [ … ] }

data will stay the array. Paging state will arrive as a sibling key next to it — never inside data, and never by changing data into an object.

So:

• Read data as the array. Do not assume it is the whole set forever.
• Ignore keys you do not recognize rather than rejecting the response.
• Do not hardcode "one request = everything" in a loop you cannot change later. Write the loop as if it might need a second page.

When it ships, the parameter names will be documented here, and the unpaginated behaviour will remain the default for existing clients.