# List Runs with Usage > Paginated list of workflow runs across the organization with usage and cost `GET /api/v1/organizations/usage/runs` Returns a paginated list of runs across all agents in your organization, including duration, cost, and usage details for each run. Use `start_date` and `end_date` (ISO 8601) to scope the window, and `page` / `limit` to paginate. Pass `filters` as a JSON-encoded string to narrow results further. To fetch the full transcript or recording for a specific run, use [Retrieve Agent Run Details](/api-reference/runs/get-run). ## OpenAPI ````yaml api-reference/openapi.json get /api/v1/organizations/usage/runs openapi: 3.1.0 info: title: Menace Voice API description: API for Menace Voice agents version: 1.0.0 servers: - url: https://voice.menaceui.com description: Production - url: http://localhost:8000 description: Local development paths: /api/v1/organizations/usage/runs: get: tags: - main summary: Get Usage History description: Get paginated workflow runs with usage for the organization. operationId: get_usage_history_api_v1_organizations_usage_runs_get parameters: - name: start_date in: query required: false schema: anyOf: - type: string - type: "null" description: ISO 8601 date-time string (UTC). Lower bound (inclusive) on `created_at`. examples: - 2026-04-01T00:00:00Z title: Start Date description: ISO 8601 date-time string (UTC). Lower bound (inclusive) on `created_at`. - name: end_date in: query required: false schema: anyOf: - type: string - type: "null" description: ISO 8601 date-time string (UTC). Upper bound (inclusive) on `created_at`. examples: - 2026-05-01T00:00:00Z title: End Date description: ISO 8601 date-time string (UTC). Upper bound (inclusive) on `created_at`. - name: page in: query required: false schema: type: integer minimum: 1 default: 1 title: Page - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Limit - name: filters in: query required: false schema: anyOf: - type: string - type: "null" description: | JSON-encoded array of filter objects. Each object has the shape: ```json { "attribute": "", "type": "", "value": } ``` Supported `attribute` / `type` / `value` combinations: | attribute | type | value shape | matches | |-----------------|---------------|----------------------------------------------|------------------------------------------------------| | `runId` | `number` | `{ "value": 12345 }` | exact run id | | `workflowId` | `number` | `{ "value": 42 }` | exact agent (workflow) id | | `campaignId` | `number` | `{ "value": 7 }` | exact campaign id | | `callerNumber` | `text` | `{ "value": "415555" }` | substring match on `initial_context.caller_number` | | `calledNumber` | `text` | `{ "value": "9911848" }` | substring match on `initial_context.called_number` | | `dispositionCode` | `multiSelect` | `{ "codes": ["XFER", "DNC"] }` | any of the codes in `gathered_context.mapped_call_disposition` | | `duration` | `numberRange` | `{ "min": 60, "max": 300 }` | call duration (seconds), inclusive bounds | | `callDirection` | `radio` | `{ "status": "inbound" }` | `inbound` or `outbound`; any other value matches all | | `callChannel` | `radio` | `{ "status": "telephony" }` | `telephony`, `web`, or `chat` — the group of run modes for that channel | Unknown attributes and unsupported `type` values are silently ignored. Date filtering on this endpoint is done via the dedicated `start_date` / `end_date` query params, not via a `dateRange` filter object. examples: - '[{"attribute":"callerNumber","type":"text","value":{"value":"415555"}}]' - '[{"attribute":"campaignId","type":"number","value":{"value":7}},{"attribute":"duration","type":"numberRange","value":{"min":60,"max":300}}]' - '[{"attribute":"dispositionCode","type":"multiSelect","value":{"codes":["XFER","DNC"]}}]' title: Filters description: | JSON-encoded array of filter objects. Each object has the shape: ```json { "attribute": "", "type": "", "value": } ``` Supported `attribute` / `type` / `value` combinations: | attribute | type | value shape | matches | |-----------------|---------------|----------------------------------------------|------------------------------------------------------| | `runId` | `number` | `{ "value": 12345 }` | exact run id | | `workflowId` | `number` | `{ "value": 42 }` | exact agent (workflow) id | | `campaignId` | `number` | `{ "value": 7 }` | exact campaign id | | `callerNumber` | `text` | `{ "value": "415555" }` | substring match on `initial_context.caller_number` | | `calledNumber` | `text` | `{ "value": "9911848" }` | substring match on `initial_context.called_number` | | `dispositionCode` | `multiSelect` | `{ "codes": ["XFER", "DNC"] }` | any of the codes in `gathered_context.mapped_call_disposition` | | `duration` | `numberRange` | `{ "min": 60, "max": 300 }` | call duration (seconds), inclusive bounds | | `callDirection` | `radio` | `{ "status": "inbound" }` | `inbound` or `outbound`; any other value matches all | | `callChannel` | `radio` | `{ "status": "telephony" }` | `telephony`, `web`, or `chat` — the group of run modes for that channel | Unknown attributes and unsupported `type` values are silently ignored. Date filtering on this endpoint is done via the dedicated `start_date` / `end_date` query params, not via a `dateRange` filter object. - name: sort_by in: query required: false schema: anyOf: - type: string - type: "null" description: Field to sort by ('duration'). Defaults to `created_at`. examples: - duration title: Sort By description: Field to sort by ('duration'). Defaults to `created_at`. - name: sort_order in: query required: false schema: type: string pattern: ^(asc|desc)$ description: Sort order ('asc' or 'desc'). default: desc title: Sort Order description: Sort order ('asc' or 'desc'). - name: authorization in: header required: false schema: anyOf: - type: string - type: "null" title: Authorization - name: X-API-Key in: header required: false schema: anyOf: - type: string - type: "null" title: X-Api-Key responses: "200": description: Successful Response content: application/json: schema: $ref: "#/components/schemas/UsageHistoryResponse" "404": description: Not found "422": description: Validation Error content: application/json: schema: $ref: "#/components/schemas/HTTPValidationError" components: schemas: HTTPValidationError: properties: detail: items: $ref: "#/components/schemas/ValidationError" type: array title: Detail type: object title: HTTPValidationError UsageHistoryResponse: properties: runs: items: $ref: "#/components/schemas/WorkflowRunUsageResponse" type: array title: Runs total_dograh_tokens: type: number title: Total Dograh Tokens total_duration_seconds: type: integer title: Total Duration Seconds total_count: type: integer title: Total Count page: type: integer title: Page limit: type: integer title: Limit total_pages: type: integer title: Total Pages type: object required: - runs - total_dograh_tokens - total_duration_seconds - total_count - page - limit - total_pages title: UsageHistoryResponse ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError WorkflowRunUsageResponse: properties: id: type: integer title: Id workflow_id: type: integer title: Workflow Id workflow_name: anyOf: - type: string - type: "null" title: Workflow Name name: type: string title: Name created_at: type: string title: Created At dograh_token_usage: type: number title: Dograh Token Usage call_duration_seconds: type: integer title: Call Duration Seconds recording_url: anyOf: - type: string - type: "null" title: Recording Url transcript_url: anyOf: - type: string - type: "null" title: Transcript Url user_recording_url: anyOf: - type: string - type: "null" title: User Recording Url bot_recording_url: anyOf: - type: string - type: "null" title: Bot Recording Url recording_public_url: anyOf: - type: string - type: "null" title: Recording Public Url transcript_public_url: anyOf: - type: string - type: "null" title: Transcript Public Url user_recording_public_url: anyOf: - type: string - type: "null" title: User Recording Public Url bot_recording_public_url: anyOf: - type: string - type: "null" title: Bot Recording Public Url public_access_token: anyOf: - type: string - type: "null" title: Public Access Token phone_number: anyOf: - type: string - type: "null" title: Phone Number description: Deprecated. Use caller_number and called_number instead. deprecated: true caller_number: anyOf: - type: string - type: "null" title: Caller Number called_number: anyOf: - type: string - type: "null" title: Called Number call_type: anyOf: - type: string - type: "null" title: Call Type mode: anyOf: - type: string - type: "null" title: Mode disposition: anyOf: - type: string - type: "null" title: Disposition initial_context: anyOf: - additionalProperties: true type: object - type: "null" title: Initial Context gathered_context: anyOf: - additionalProperties: true type: object - type: "null" title: Gathered Context charge_usd: anyOf: - type: number - type: "null" title: Charge Usd type: object required: - id - workflow_id - workflow_name - name - created_at - dograh_token_usage - call_duration_seconds title: WorkflowRunUsageResponse ````