Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Sort & filter

Filtering is per-endpoint, not a uniform query language. Each list endpoint documents the exact query parameters it accepts in its API reference — there is no global sort= or generic field-equals filter that works everywhere. Passing a parameter an endpoint doesn't recognize is silently ignored: you get the full, unfiltered list back. Always check the endpoint's reference page for its supported parameters before relying on a filter.

Filter

Exact match by external ID

The most widely supported filter is externalId, which returns records whose external identifier matches exactly. It's available on connections, exports, imports, flows, lookup caches, and file definitions:

curl "$BASE/v1/exports?externalId=my-export-key" -H "Authorization: Bearer $TOKEN"

Scoping to an integration

Exports, imports, flows, and connections are not filterable by _integrationId as a query parameter — those resources don't carry a direct integration reference (an export is attached to a flow, and the flow belongs to the integration). To list everything in a specific integration, use the nested route instead:

# All exports in an integration
curl "$BASE/v1/integrations/5f83a9b2c7d3e8f1a2b3c4d5/exports" -H "Authorization: Bearer $TOKEN"

# Also available: /flows, /imports, /connections
curl "$BASE/v1/integrations/5f83a9b2c7d3e8f1a2b3c4d5/flows"   -H "Authorization: Bearer $TOKEN"

Endpoints with richer filters

A few high-volume endpoints expose dedicated filter parameters. Jobs is the broadest:

# Failed flow jobs in an integration, created in a time window
curl "$BASE/v1/jobs?_integrationId=5f83a9b2c7d3e8f1a2b3c4d5&status=failed&createdAt_gte=2026-04-01T00:00:00Z&createdAt_lte=2026-04-30T23:59:59Z"

Jobs supports _integrationId, _flowId, _exportId, _importId, status, type, the createdAt_gte / createdAt_lte time bounds, and numError_gte / numError_lte (and the numSuccess / numIgnore equivalents).

Audit has its own set:

Audit supports resourceType, _resourceId, _byUserId, source, action, and the from / to time bounds. Note the parameter names differ per endpoint — jobs uses createdAt_gte / createdAt_lte, audit uses from / to.

Field projection

To trim the payload, use include or exclude (mutually exclusive):

  • include — comma-separated fields to project. Triggers summary projection: the response is a minimal identity set (_id, name, plus resource-specific fields) with your requested fields added. Supports dot notation for nested fields.

  • exclude — comma-separated fields to strip from the default response. Returns the full record minus those fields; protected identity fields like name can't be stripped.

When you're listing large collections, this is the single biggest performance win.

Sort

There is no universal sort parameter. Sorting is offered only by specific endpoints — for example, the marketplace listing accepts sort_by (numInstalls, name, lastModified) and flow execution logs accept sortOrder (asc / desc). Check the endpoint's reference page; if it documents no sort parameter, results come back in server-default order and you sort client-side.

Pagination

List endpoints page with limit (page size) plus a server-provided cursor. When more pages remain, the response carries an RFC-5988 Link header with a rel="next" entry; it's absent on the final page. Any filters you applied are baked into that next URL — follow the header exactly as-is rather than re-appending parameters. See Pagination for the iteration pattern.

When the CLI is faster

For ad-hoc exploration, a few CLI list commands accept server-side filters (notably jobs list and audit list); most resource listings don't, so filter with --jq on the client side:

See the CLI Reference.

PreviousPagination
NextRate limits

Last updated

Was this helpful?