> ## Documentation Index > Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt > Use this file to discover all available pages before exploring further. # List traces > Get paginated list of traces with optional filtering ## OpenAPI ````yaml https://control-plane.kubiya.ai/api/openapi.json get /api/v1/traces openapi: 3.1.0 info: title: Agent Control Plane API description: Multi-tenant agent orchestration with Temporal workflows version: 1.0.0 servers: [] security: - BearerAuth: [] tags: - name: health description: πŸ₯ **Health & Status** - Check API health and availability - name: authentication description: πŸ” **Authentication** - Token validation and auth management - name: agents description: πŸ€– **Agents** - Create and manage AI agents with custom capabilities - name: skills description: πŸ› οΈ **Tool Sets** - Manage agent skills and tool configurations - name: integrations description: πŸ”Œ **Integrations** - Connect to external services (Kubiya managed) - name: custom-integrations description: >- βš™οΈ **Custom Integrations** - User-defined integration instances with env vars, secrets, and files - name: integration-templates description: >- πŸ“¦ **Integration Templates** - Pre-configured templates for common services (PostgreSQL, Redis, MongoDB, etc.) - name: secrets description: πŸ”‘ **Secrets** - Secure credential storage and retrieval - name: teams description: πŸ‘₯ **Teams** - Team management and collaboration - name: workflows description: πŸ“Š **Workflows** - Multi-step automation and orchestration - name: executions description: ▢️ **Executions** - Track and monitor workflow runs - name: jobs description: ⏰ **Jobs** - Scheduled and webhook-triggered tasks - name: policies description: πŸ›‘οΈ **Policies** - Access control and security policies - name: analytics description: πŸ“ˆ **Analytics** - Usage metrics and performance monitoring - name: projects description: πŸ“ **Projects** - Project organization and management - name: environments description: 🌍 **Environments** - Environment configuration (dev, staging, prod) - name: models description: 🧠 **Models** - LLM model configuration and management - name: runtimes description: ⚑ **Runtimes** - Agent execution runtime environments - name: workers description: πŸ‘· **Workers** - Worker registration and heartbeat monitoring - name: storage description: πŸ’Ύ **Storage** - File storage and cloud integration - name: context-graph description: πŸ•ΈοΈ **Context Graph** - Knowledge graph and context management - name: temporal-workflows description: >- βš™οΈ **Temporal Workflows** - Background workflows for context graph ingestion, connector operations, and scheduled jobs - name: templates description: πŸ“ **Templates** - Reusable configuration templates paths: /api/v1/traces: get: summary: List traces description: Get paginated list of traces with optional filtering operationId: list_traces_api_v1_traces_get parameters: - name: page in: query required: false schema: type: integer minimum: 1 description: Page number default: 1 title: Page description: Page number - name: page_size in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Items per page default: 20 title: Page Size description: Items per page - name: sort in: query required: false schema: type: string description: Sort field with - prefix for descending default: '-started_at' title: Sort description: Sort field with - prefix for descending - name: status in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Filter by status: success, error, running' title: Status description: 'Filter by status: success, error, running' - name: time_from in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: Filter traces starting after this time title: Time From description: Filter traces starting after this time - name: time_to in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: Filter traces starting before this time title: Time To description: Filter traces starting before this time - name: search in: query required: false schema: anyOf: - type: string - type: 'null' description: Search in trace/span names title: Search description: Search in trace/span names - name: execution_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by linked execution ID title: Execution Id description: Filter by linked execution ID - name: service_name in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by service name title: Service Name description: Filter by service name - name: user_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by user ID title: User Id description: Filter by user ID - name: has_errors in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Filter traces with/without errors title: Has Errors description: Filter traces with/without errors responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TraceListResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: TraceListResponse: properties: items: items: $ref: '#/components/schemas/TraceListItem' type: array title: Items total: type: integer title: Total page: type: integer title: Page page_size: type: integer title: Page Size total_pages: type: integer title: Total Pages has_next: type: boolean title: Has Next has_previous: type: boolean title: Has Previous type: object required: - items - total - page - page_size - total_pages - has_next - has_previous title: TraceListResponse description: Paginated trace list response HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TraceListItem: properties: id: type: string title: Id trace_id: type: string title: Trace Id organization_id: type: string title: Organization Id name: type: string title: Name service_name: anyOf: - type: string - type: 'null' title: Service Name status: $ref: '#/components/schemas/TraceStatus' execution_id: anyOf: - type: string - type: 'null' title: Execution Id execution_type: anyOf: - type: string - type: 'null' title: Execution Type user_id: anyOf: - type: string - type: 'null' title: User Id user_email: anyOf: - type: string - type: 'null' title: User Email user_name: anyOf: - type: string - type: 'null' title: User Name user_avatar: anyOf: - type: string - type: 'null' title: User Avatar started_at: type: string format: date-time title: Started At ended_at: anyOf: - type: string format: date-time - type: 'null' title: Ended At duration_ms: anyOf: - type: integer - type: 'null' title: Duration Ms span_count: type: integer title: Span Count default: 0 error_count: type: integer title: Error Count default: 0 created_at: type: string format: date-time title: Created At updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At type: object required: - id - trace_id - organization_id - name - status - started_at - created_at title: TraceListItem description: Trace list item for list view ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError TraceStatus: type: string enum: - success - error - running title: TraceStatus description: Trace status enum securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'Enter your Kubiya API token (format: Bearer )' ````