Skip to main content
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 via the limit and cursor parameters.

​
Filters by endpoint

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.
curl "https://api.deck.co/v2/credentials?source_id=src_abc&status=verified" \
  -H "Authorization: Bearer sk_live_..."
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.
curl "https://api.deck.co/v2/tasks?agent_id=agt_abc&status=live" \
  -H "Authorization: Bearer sk_live_..."
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, cancelling, 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).
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_..."
GET /v2/event-destinations
​
status
enum
Filter by destination status. One of pending_verification, active, inactive.
curl "https://api.deck.co/v2/event-destinations?status=active" \
  -H "Authorization: Bearer sk_live_..."
GET /v2/event-destinations/{destination_id}/event-deliveries
​
status
enum
Filter by delivery status. One of success, failure.
curl "https://api.deck.co/v2/event-destinations/evtd_abc/event-deliveries?status=failure" \
  -H "Authorization: Bearer sk_live_..."
GET /v2/events
​
type
string
Filter by event type (e.g., task_run.completed, credential.connected).
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. 
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 for details.

Pagination

Navigate large result sets with cursor-based pagination.

Using the API

Authentication, base URLs, and request conventions.