> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/api/using-the-api/sorting-filtering.md).

# 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:

```bash
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:

```bash
# 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:

```bash
# 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:

```bash
curl "$BASE/v1/audit?source=ui&action=update&from=2026-04-01T00:00:00Z&to=2026-04-30T23:59:59Z"
```

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.

```bash
curl "$BASE/v1/integrations?include=_integrationId,disabled,lastModified"
```

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](/api/using-the-api/pagination.md) 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:

```bash
# audit: server-side filters
celigo audit list --source ui --start-date 2026-04-01T00:00:00Z --end-date 2026-04-30T23:59:59Z

# jobs: server-side filters
celigo jobs list --flow 5f83a9b2c7d3e8f1a2b3c4d5 --status failed

# other resources: filter client-side with --jq
celigo flows list       --jq '[.[] | select(._integrationId == "5f83a9b2c7d3e8f1a2b3c4d5" and .disabled == false)]'
celigo connections list --jq '[.[] | select(.type == "netsuite")]'
```

See the [CLI Reference](https://developer.celigo.com/cli).