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/connections
​
source_id
string
Return only connections for a specific source.
​
status
enum
Filter by connection status. One of connecting, interaction_required, connected, disconnected, terminated.
​
external_id
string
Filter by the external ID you assigned when creating the connection. Useful for finding all connections belonging to a specific user in your system.
curl "https://api.deck.co/v2/connections?source_id=src_abc&status=connected" \
  -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.
​
connection_id
string
Filter by connection. Returns only runs that used a specific connection.
​
source_id
string
Filter by source.
​
task_id
string
Filter by task.
​
workflow_id
string
Filter by workflow.
​
status
enum
Filter by run status. One of queued, running, interaction_required, completed, canceled, failed.
​
result
enum
Filter by run result. One of success, failure, unknown.
​
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&result=success&created_after=2025-01-01T00:00:00Z" \
  -H "Authorization: Bearer sk_live_..."
GET /v2/workflow-runs
​
workflow_id
string
Return only runs for a specific workflow.
​
status
enum
Filter by run status. One of queued, running, sleeping, interaction_required, completed, failed, canceled.
curl "https://api.deck.co/v2/workflow-runs?workflow_id=wflo_abc&status=completed" \
  -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, skipped.
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, connection.connected).
​
created_after
datetime
Return events created after this timestamp (ISO 8601).
​
created_before
datetime
Return events created before this timestamp (ISO 8601).
curl "https://api.deck.co/v2/events?type=task_run.completed&created_after=2025-06-01T00:00:00Z" \
  -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
  • GET /v2/workflows

​
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.