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

GET /v2/credentials
​
string
Return only credentials for a specific source.
​
enum
Filter by credential status. One of unverified, verified, invalid, deleted.
​
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.
GET /v2/tasks
​
string
Return only tasks belonging to a specific agent.
​
enum
Filter by task status. One of learning, test, live.
GET /v2/task-runs
​
string
Filter by agent.
​
string
Filter by credential. Returns only runs that used a specific credential.
​
string
Filter by source.
​
string
Filter by task.
​
enum
Filter by run status. One of queued, running, canceling, interaction_required, review_required, completed, canceled, failed.
​
enum
Filter by run result. One of success, failure, unknown. Maps to the result field on the task run object.
​
datetime
Return runs created after this timestamp (ISO 8601).
​
datetime
Return runs created before this timestamp (ISO 8601).
​
string
Free-text search matching task name, task ID, or task run ID.
GET /v2/event-destinations/{destination_id}/event-deliveries
​
enum
Filter by delivery status. One of success, failure.
​
string
Filter by event type, e.g. task_run.completed.
GET /v2/events
​
string
Filter by event type (e.g., task_run.completed, credential.verified).
​
datetime
Return events created after this timestamp (ISO 8601).
​
datetime
Return events created before this timestamp (ISO 8601).

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

Pagination

Navigate large result sets with cursor-based pagination.

Using the API

Authentication, base URLs, and request conventions.