Get Usage History

GET /api/v1/organizations/usage/runs — request parameters and responses from the Menace Voice API schema.

3 min read

get/api/v1/organizations/usage/runs

Request example

curl --request GET \
  --url https://voice.menaceui.com/api/v1/organizations/usage/runs \
  --header 'authorization: <string>' \
  --header 'X-API-Key: <string>'

Response

{
  "runs": [
    {
      "id": 1,
      "workflow_id": 1,
      "workflow_name": "<string>",
      "name": "<string>",
      "created_at": "<string>",
      "dograh_token_usage": 1,
      "call_duration_seconds": 1,
      "recording_url": "<string>",
      "transcript_url": "<string>",
      "user_recording_url": "<string>",
      "bot_recording_url": "<string>",
      "recording_public_url": "<string>",
      "transcript_public_url": "<string>",
      "user_recording_public_url": "<string>",
      "bot_recording_public_url": "<string>",
      "public_access_token": "<string>",
      "phone_number": "<string>",
      "caller_number": "<string>",
      "called_number": "<string>",
      "call_type": "<string>",
      "mode": "<string>",
      "disposition": "<string>",
      "initial_context": {},
      "gathered_context": {},
      "charge_usd": 1
    }
  ],
  "total_dograh_tokens": 1,
  "total_duration_seconds": 1,
  "total_count": 1,
  "page": 1,
  "limit": 1,
  "total_pages": 1
}

get/api/v1/organizations/usage/runs

See authentication for workspace API access. Public embed and artifact endpoints use their documented session or access tokens.

Query parameters

start_datestring · null#

ISO 8601 date-time string (UTC). Lower bound (inclusive) on created_at.

end_datestring · null#

ISO 8601 date-time string (UTC). Upper bound (inclusive) on created_at.

pageinteger#

Default: 1

Range: >= 1

limitinteger#

Default: 50

Range: 1–100

filtersstring · null#

JSON-encoded array of filter objects. Each object has the shape:

{ "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_bystring · null#

Field to sort by ('duration'). Defaults to created_at.

sort_orderstring#

Sort order ('asc' or 'desc').

Default: "desc"

Pattern: ^(asc|desc)$

Headers

authorizationstring · null#

X-API-Keystring · null#

Responses

application/json

Successful Response

runsobject[]required#

Show child attributes

idintegerrequired#

workflow_idintegerrequired#

workflow_namestring · nullrequired#

Show child attributes

Any of

namestringrequired#

created_atstringrequired#

dograh_token_usagenumberrequired#

call_duration_secondsintegerrequired#

recording_urlstring · null#

Show child attributes

Any of

transcript_urlstring · null#

Show child attributes

Any of

user_recording_urlstring · null#

Show child attributes

Any of

bot_recording_urlstring · null#

Show child attributes

Any of

recording_public_urlstring · null#

Show child attributes

Any of

transcript_public_urlstring · null#

Show child attributes

Any of

user_recording_public_urlstring · null#

Show child attributes

Any of

bot_recording_public_urlstring · null#

Show child attributes

Any of

public_access_tokenstring · null#

Show child attributes

Any of

phone_numberstring · nulldeprecated#

Deprecated. Use caller_number and called_number instead.

Show child attributes

Any of

caller_numberstring · null#

Show child attributes

Any of

called_numberstring · null#

Show child attributes

Any of

call_typestring · null#

Show child attributes

Any of

modestring · null#

Show child attributes

Any of

dispositionstring · null#

Show child attributes

Any of

initial_contextobject · null#

Show child attributes

Any of

gathered_contextobject · null#

Show child attributes

Any of

charge_usdnumber · null#

Show child attributes

Any of

total_dograh_tokensnumberrequired#

total_duration_secondsintegerrequired#

total_countintegerrequired#

pageintegerrequired#

limitintegerrequired#

total_pagesintegerrequired#

Create Mps Credit Purchase Url Download Usage Runs Report