> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deck.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtering list endpoints

> Narrow down API results using query parameters on list endpoints.

Most list endpoints accept query parameters that let you filter results server-side. This is more efficient than fetching everything and filtering in your application. All filters are combined with AND logic.

Every list endpoint also supports [cursor-based pagination](https://docs.deck.co/api/pagination.md) via the `limit` and `cursor` parameters.

Some filters accept multiple values as a comma-separated list and match any of them: `status`, `source_id`, and `outcome` on task runs; `source_id` and `status` on credentials; and `type` on events.

## Filters by endpoint

> [accordion] List credentials
>
> `GET /v2/credentials`
>
> **source\_id** `string`
>
> Return only credentials for a specific source.
>
> **status** `enum`
>
> Filter by credential status. One of `unverified`, `verified`, `invalid`, `deleted`.
>
> **external\_id** `string`
>
> Filter by the external ID you assigned when creating the credential. Useful for finding all credentials belonging to a specific user in your system.
>
> ```bash theme={null}
> curl "https://api.deck.co/v2/credentials?source_id=src_abc&status=verified" \
>   -H "Authorization: Bearer sk_live_..."
> ```

> [accordion] List tasks
>
> `GET /v2/tasks`
>
> **agent\_id** `string`
>
> Return only tasks belonging to a specific agent.
>
> **status** `enum`
>
> Filter by task status. One of `learning`, `test`, `live`.
>
> ```bash theme={null}
> curl "https://api.deck.co/v2/tasks?agent_id=agt_abc&status=live" \
>   -H "Authorization: Bearer sk_live_..."
> ```

> [accordion] List task runs
>
> `GET /v2/task-runs`
>
> **agent\_id** `string`
>
> Filter by agent.
>
> **credential\_id** `string`
>
> Filter by credential. Returns only runs that used a specific credential.
>
> **source\_id** `string`
>
> Filter by source.
>
> **task\_id** `string`
>
> Filter by task.
>
> **status** `enum`
>
> Filter by run status. One of `queued`, `running`, `canceling`, `interaction_required`, `review_required`, `completed`, `canceled`, `failed`.
>
> **outcome** `enum`
>
> Filter by run result. One of `success`, `failure`, `unknown`. Maps to the `result` field on the task run object.
>
> **created\_after** `datetime`
>
> Return runs created after this timestamp (ISO 8601).
>
> **created\_before** `datetime`
>
> Return runs created before this timestamp (ISO 8601).
>
> **search** `string`
>
> Free-text search matching task name, task ID, or task run ID.
>
> ```bash theme={null}
> curl "https://api.deck.co/v2/task-runs?agent_id=agt_abc&status=completed&outcome=success&created_after=2026-01-01T00:00:00Z" \
>   -H "Authorization: Bearer sk_live_..."
> ```

> [accordion] List deliveries for a destination
>
> `GET /v2/event-destinations/{destination_id}/event-deliveries`
>
> **status** `enum`
>
> Filter by delivery status. One of `success`, `failure`.
>
> **type** `string`
>
> Filter by event type, e.g. `task_run.completed`.
>
> ```bash theme={null}
> curl "https://api.deck.co/v2/event-destinations/evtd_abc/event-deliveries?status=failure&type=task_run.completed" \
>   -H "Authorization: Bearer sk_live_..."
> ```

> [accordion] List events
>
> `GET /v2/events`
>
> **type** `string`
>
> Filter by event type (e.g., `task_run.completed`, `credential.verified`).
>
> **created\_after** `datetime`
>
> Return events created after this timestamp (ISO 8601).
>
> **created\_before** `datetime`
>
> Return events created before this timestamp (ISO 8601).
>
> ```bash theme={null}
> curl "https://api.deck.co/v2/events?type=task_run.completed" \
>   -H "Authorization: Bearer sk_live_..."
> ```

## Endpoints without filters

The following list endpoints only support pagination (`limit` and `cursor`) with no additional filters:

* `GET /v2/agents`
* `GET /v2/sources`

## Combining filters with date ranges

For endpoints that support `created_after` and `created_before`, you can combine them to query a specific window of time.

```bash theme={null}
curl "https://api.deck.co/v2/task-runs?created_after=2026-06-01T00:00:00Z&created_before=2026-06-30T23:59:59Z&status=failed" \
  -H "Authorization: Bearer sk_live_..."
```

This returns all failed task runs from June 2026. Combine date ranges with other filters to build precise queries for dashboards, reports, or debugging.

Both bounds are inclusive, so a record created exactly at the `created_after` or `created_before` timestamp is returned. Always send timestamps in UTC ISO 8601 with a trailing `Z` (for example, `2026-06-01T00:00:00Z`) so results are consistent across endpoints.

## Tips

* **Filter server-side.** Fetching all records and filtering in your app wastes bandwidth and API quota.
* **Combine filters.** All query parameters are AND-combined, so adding more filters narrows results.
* **Use date ranges for historical queries.** `created_after` and `created_before` are the most efficient way to pull data for a time window.
* **Pair with pagination.** Large result sets should use `limit` and `cursor` together with filters. See the [pagination guide](https://docs.deck.co/api/pagination.md) for details.

> [card] [Pagination](https://docs.deck.co/api/pagination.md)
>
> Navigate large result sets with cursor-based pagination.

> [card] [Using the API](https://docs.deck.co/api/using-the-api.md)
>
> Authentication, base URLs, and request conventions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.