Pagination and Filtering

List endpoints use cursor pagination. Pass limit to choose a page size, then pass pagination.next_cursor as cursor to request the next page.

Pagination

Runs default to limit=50 and are capped at 100. Tools, agents, guidelines, guardrails, and runbooks default to limit=100 and are capped at 200.

curl "https://app.useduckie.ai/api/v1/runs?limit=50" \
  -H "Authorization: Bearer dk_live_your_api_key"

{
  "data": [],
  "pagination": {
    "limit": 50,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNi0wM1QwMDowMDowMC4wMDBaIiwiaWQiOiIwMDAwMDAwMC0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMDAwMDAifQ",
    "has_more": true
  }
}

Use the returned cursor as an opaque string:

curl "https://app.useduckie.ai/api/v1/runs?limit=50&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wNi0wM1QwMDowMDowMC4wMDBaIiwiaWQiOiIwMDAwMDAwMC0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMDAwMDAifQ" \
  -H "Authorization: Bearer dk_live_your_api_key"

Runs Filters

GET /api/v1/runs supports these filters:

Filter	Behavior
`created_after`	ISO timestamp lower bound
`created_before`	ISO timestamp upper bound
`status`	One or more of `completed`, `running`, `failed`, `cancelled`, `paused`
`ticket_id`	Exact source ticket or conversation ID
`agent_id`	Agent UUID
`source`	Exact source match
`resolution_type`	One or more of `deflected`, `resolved`, `escalated`, `pending`
`duration[eq]`	Exact duration in seconds
`duration[gt]`	Duration greater than a number of seconds
`duration[gte]`	Duration greater than or equal to a number of seconds
`duration[lt]`	Duration less than a number of seconds
`duration[lte]`	Duration less than or equal to a number of seconds
`tool_name`	Exact recorded tool name from a tool-call step
`search`	Text search over ticket title, ticket ID, and agent name
`metadata.<key>`	Metadata key/value filter

Repeat status, ticket_id, agent_id, source, resolution_type, or tool_name to OR together multiple values.

curl "https://app.useduckie.ai/api/v1/runs?status=completed&status=failed&duration[gte]=60&duration[lt]=300" \
  -H "Authorization: Bearer dk_live_your_api_key"

Tool-Name Filters

Run tool filters use the recorded run_steps.tool_name value for steps where type is tool_call. Display labels are not accepted as filter values. Use the tool-options endpoint to discover valid historical values:

curl "https://app.useduckie.ai/api/v1/runs/tool-options" \
  -H "Authorization: Bearer dk_live_your_api_key"

{
  "data": [
    {
      "tool_name": "knowledge_search",
      "display_name": "Knowledge Search",
      "run_count": 42
    }
  ]
}

Tools Filters

GET /api/v1/tools supports these filters:

Filter	Behavior
`type`	One or more of `duckie_tool`, `app_tool`, `custom_tool`, `mcp_tool`
`search`	Search tool name, description, app integration name, and MCP server name
`is_write_action`	`true` or `false`
`requires_approval`	`true` or `false`
`integration_id`	Match app tools for one integration
`mcp_server_id`	Match MCP tools for one server UUID

curl "https://app.useduckie.ai/api/v1/tools?type=custom_tool&requires_approval=true" \
  -H "Authorization: Bearer dk_live_your_api_key"

Guardrail Filters

GET /api/v1/guardrails accepts type=escalation or type=restriction.

Guides

API Reference

Runs Filters

Tool-Name Filters

Tools Filters

Guardrail Filters

​Pagination

​Runs Filters

​Tool-Name Filters

​Tools Filters

​Guardrail Filters

Pagination

Runs Filters

Tool-Name Filters

Tools Filters

Guardrail Filters