Usage

Retrieve aggregated usage data for your organization, including total session duration, session counts, and per-agent breakdowns. Data is computed from pre-processed daily summaries up to yesterday (today's data is not included).

Authentication#

All API requests require an API key. Generate one from your account settings.

Include the API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Authorization#

Requires organization admin or owner role. Requests from users without the required role return 403 Forbidden.

Base URL#

https://api.voicerun.com/v1/usage

Get Usage Report#

Retrieve usage data for a custom date range.

GET /v1/usage/report

Query Parameters#

Example Request#

GET /v1/usage/report?startDate=2025-01-01&endDate=2025-01-31

Example Response#

{
  "data": {
    "startDate": "2025-01-01",
    "endDate": "2025-01-31",
    "organizationId": "org_abc123",
    "usage": {
      "totalDurationMs": 3600000,
      "totalDurationMinutes": 60,
      "totalSessions": 150,
      "agentBreakdown": [
        {
          "agentId": "agent_xyz",
          "agentName": "Support Agent",
          "durationMs": 2400000,
          "durationMinutes": 40,
          "sessionCount": 100
        },
        {
          "agentId": "agent_abc",
          "agentName": "Sales Agent",
          "durationMs": 1200000,
          "durationMinutes": 20,
          "sessionCount": 50
        }
      ]
    }
  }
}

Get Monthly Usage#

Retrieve usage data for a specific month.

GET /v1/usage/monthly

Query Parameters#

Example Request#

GET /v1/usage/monthly?year=2025&month=1

Example Response#

Same shape as Get Usage Report. The startDate and endDate reflect the first and last day of the requested month.

Tag-Based Usage#

The by-tags endpoints break down usage by the tags attached to your sessions. This is useful when you tag sessions with metadata like department, region, or campaign and want to see usage across those dimensions.

The tags parameter is optional. When omitted, results are broken down by every unique tag combination. When provided, it acts as a filter — only sessions whose tags contain all of the specified key-value pairs are included. For example, filtering by {"department":"sales"} returns sessions tagged with department=sales, broken down by any other tags those sessions have (like region).

Note: Sessions without any tags are excluded from by-tags results. Only sessions with at least one tag are included.

Get Usage Report by Tags#

Retrieve usage data for a date range, broken down by session tags.

GET /v1/usage/report/by-tags

Query Parameters#

Example Request#

GET /v1/usage/report/by-tags?startDate=2025-01-01&endDate=2025-01-31&tags={"department":"sales"}

Example Response#

{
  "data": {
    "totalDurationMs": 3600000,
    "totalDurationMinutes": 60,
    "totalSessions": 150,
    "breakdown": [
      {
        "agentId": "agent_xyz",
        "agentName": "Support Agent",
        "tags": { "department": "sales", "region": "us-east" },
        "durationMs": 2400000,
        "durationMinutes": 40,
        "sessionCount": 100
      },
      {
        "agentId": "agent_abc",
        "agentName": "Outbound Agent",
        "tags": { "department": "sales", "region": "eu-west" },
        "durationMs": 1200000,
        "durationMinutes": 20,
        "sessionCount": 50
      }
    ]
  }
}

Get Monthly Usage by Tags#

Retrieve usage data for a specific month, broken down by session tags.

GET /v1/usage/monthly/by-tags

Query Parameters#

Example Request#

GET /v1/usage/monthly/by-tags?year=2025&month=1&tags={"department":"sales"}

Example Response#

Same shape as Get Usage Report by Tags.

Response Types#

UsagePeriodData#

Returned by the /report and /monthly endpoints.

UsageTagData#

Returned by the /report/by-tags and /monthly/by-tags endpoints.

Error Responses#

Related#

• Session Data — List and filter individual sessions
• Latency Metrics — Per-turn performance metrics