> ## 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](/api/pagination) via the `limit` and `cursor` parameters.

## Filters by endpoint

<AccordionGroup>
  <Accordion title="List credentials">
    `GET /v2/credentials`

    <ResponseField name="source_id" type="string">
      Return only credentials for a specific source.
    </ResponseField>

    <ResponseField name="status" type="enum">
      Filter by credential status. One of `unverified`, `verified`, `invalid`, `deleted`.
    </ResponseField>

    <ResponseField name="external_id" type="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.
    </ResponseField>

    ```bash theme={null}
    curl "https://api.deck.co/v2/credentials?source_id=src_abc&status=verified" \
      -H "Authorization: Bearer sk_live_..."
    ```
  </Accordion>

  <Accordion title="List tasks">
    `GET /v2/tasks`

    <ResponseField name="agent_id" type="string">
      Return only tasks belonging to a specific agent.
    </ResponseField>

    <ResponseField name="status" type="enum">
      Filter by task status. One of `learning`, `test`, `live`.
    </ResponseField>

    ```bash theme={null}
    curl "https://api.deck.co/v2/tasks?agent_id=agt_abc&status=live" \
      -H "Authorization: Bearer sk_live_..."
    ```
  </Accordion>

  <Accordion title="List task runs">
    `GET /v2/task-runs`

    <ResponseField name="agent_id" type="string">
      Filter by agent.
    </ResponseField>

    <ResponseField name="credential_id" type="string">
      Filter by credential. Returns only runs that used a specific credential.
    </ResponseField>

    <ResponseField name="source_id" type="string">
      Filter by source.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Filter by task.
    </ResponseField>

    <ResponseField name="status" type="enum">
      Filter by run status. One of `queued`, `running`, `cancelling`, `interaction_required`, `review_required`, `completed`, `canceled`, `failed`.
    </ResponseField>

    <ResponseField name="outcome" type="enum">
      Filter by run result. One of `success`, `failure`, `unknown`. Maps to the `result` field on the task run object.
    </ResponseField>

    <ResponseField name="created_after" type="datetime">
      Return runs created after this timestamp (ISO 8601).
    </ResponseField>

    <ResponseField name="created_before" type="datetime">
      Return runs created before this timestamp (ISO 8601).
    </ResponseField>

    ```bash theme={null}
    curl "https://api.deck.co/v2/task-runs?agent_id=agt_abc&status=completed&outcome=success&created_after=2025-01-01T00:00:00Z" \
      -H "Authorization: Bearer sk_live_..."
    ```
  </Accordion>

  <Accordion title="List event destinations">
    `GET /v2/event-destinations`

    <ResponseField name="status" type="enum">
      Filter by destination status. One of `pending_verification`, `active`, `inactive`.
    </ResponseField>

    ```bash theme={null}
    curl "https://api.deck.co/v2/event-destinations?status=active" \
      -H "Authorization: Bearer sk_live_..."
    ```
  </Accordion>

  <Accordion title="List deliveries for a destination">
    `GET /v2/event-destinations/{destination_id}/event-deliveries`

    <ResponseField name="status" type="enum">
      Filter by delivery status. One of `success`, `failure`.
    </ResponseField>

    ```bash theme={null}
    curl "https://api.deck.co/v2/event-destinations/evtd_abc/event-deliveries?status=failure" \
      -H "Authorization: Bearer sk_live_..."
    ```
  </Accordion>

  <Accordion title="List events">
    `GET /v2/events`

    <ResponseField name="type" type="string">
      Filter by event type (e.g., `task_run.completed`, `credential.connected`).
    </ResponseField>

    ```bash theme={null}
    curl "https://api.deck.co/v2/events?type=task_run.completed" \
      -H "Authorization: Bearer sk_live_..."
    ```
  </Accordion>
</AccordionGroup>

## 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=2025-06-01T00:00:00Z&created_before=2025-06-30T23:59:59Z&status=failed" \
  -H "Authorization: Bearer sk_live_..."
```

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

## 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](/api/pagination) for details.

<CardGroup cols={2}>
  <Card title="Pagination" icon="arrow-right" href="/api/pagination">
    Navigate large result sets with cursor-based pagination.
  </Card>

  <Card title="Using the API" icon="code" href="/api/using-the-api">
    Authentication, base URLs, and request conventions.
  </Card>
</CardGroup>