# Get Usage History > GET /api/v1/organizations/usage/runs — request parameters and responses from the Menace Voice API schema. `GET /api/v1/organizations/usage/runs` {/* Generated by scripts/sync_docs_api.mjs. Edit the API schema source to change the contract. */} See [authentication](/api-reference/authentication) for workspace API access. Public embed and artifact endpoints use their documented session or access tokens. ## API contract for documentation tools Generated from the OpenAPI schema. Do not infer a different parameter type from an example. Authentication headers are alternatives as explained in the authentication guide. ### Parameters | Name | Location | Type | Required | Description and constraints | | --- | --- | --- | --- | --- | | start_date | query | string or null | no | ISO 8601 date-time string (UTC). Lower bound (inclusive) on `created_at`. | | end_date | query | string or null | no | ISO 8601 date-time string (UTC). Upper bound (inclusive) on `created_at`. | | page | query | integer | no | default: 1; minimum: 1 | | limit | query | integer | no | default: 50; minimum: 1; maximum: 100 | | filters | query | string or null | no | JSON-encoded array of filter objects. Each object has the shape: ```json { "attribute": "<name>", "type": "<type>", "value": <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. | | sort_by | query | string or null | no | Field to sort by ('duration'). Defaults to `created_at`. | | sort_order | query | string | no | Sort order ('asc' or 'desc'). default: "desc"; pattern: "^(asc\|desc)$" | | authorization | header | string or null | no | | | X-API-Key | header | string or null | no | | ### Response 200 Successful Response application/json: UsageHistoryResponse (object). | Field | Type | Required | Description and constraints | | --- | --- | --- | --- | | runs | array of WorkflowRunUsageResponse (object) | yes | | | total_dograh_tokens | number | yes | | | total_duration_seconds | integer | yes | | | total_count | integer | yes | | | page | integer | yes | | | limit | integer | yes | | | total_pages | integer | yes | | ### Response 404 Not found ### Response 422 Validation Error application/json: HTTPValidationError (object). | Field | Type | Required | Description and constraints | | --- | --- | --- | --- | | detail | array of ValidationError (object) | no | | ## 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 ````