Request Logs

Two read endpoints return the data behind the Logs and Usage pages, so you can pull it into your own monitoring, alerting or cost reports.

Endpoint	Returns
`GET /v3/requests`	Each write call, newest first, with the job it was charged for and its charge
`GET /v3/usage`	Spend per API key, or per tag, product, endpoint or channel, per credit pool

Access

Authenticate with an API key or an OAuth token. A restricted key needs the usage:read scope.
Workspace admins see every call and every key. Other members see the calls they made and the keys they own.
Times are Unix seconds. start_time and end_time are required, and one request covers up to 90 days.
Both endpoints page with limit and token: pass the previous response’s next_token as token while has_more is true.

Request log

GET /v3/requests lists write calls (POST, PUT, PATCH, DELETE). Calls are kept for 12 months.

curl "https://api.heygen.com/v3/requests?start_time=1762214400&end_time=1762300800&status=failed" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Parameter	Description
`start_time`, `end_time`	Range, Unix seconds. Up to 90 days.
`status`	`succeeded` (HTTP status below 400) or `failed` (400 and above).
`api_key_id`	Calls made with this key.
`endpoint`	Calls to this route template, for example `/v3/videos/{video_id}`.
`request_id`	The call with this request ID.
`job_id`	The calls charged for this job, for example a video ID. Use `request_id` or `job_id`, one per request.
`limit`	Calls per page, 1 to 100. Default 50.
`token`	The `next_token` of the previous page.

Find a call

Every response carries its request ID in the X-HeyGen-Request-Id header, and error bodies include it too. Log it with your own records, then pass it as request_id to see how the call was handled and charged. To trace a video back to the calls that created it, pass the video ID as job_id.

Response

{
  "data": [
    {
      "request_id": "8f2c1e0a7b9d4c3e",
      "created_at": 1762291520,
      "method": "POST",
      "endpoint": "/v3/videos",
      "status_code": 200,
      "error_code": null,
      "latency_ms": 412,
      "auth_method": "api_key",
      "api_key": { "id": "key_7f3a", "name": "Production", "suffix": "x9Qa" },
      "project": "onboarding",
      "environment": "production",
      "job": { "id": "vid_4b21c8", "type": "video", "status": "completed", "failure_code": null },
      "charge": { "amount": 12.5, "unit": "credits", "amount_usd": null, "refunded": false, "other_pools": 0 },
      "charge_recorded": true
    }
  ],
  "has_more": false,
  "next_token": null
}

Field	Description
`endpoint`	The route template, such as `/v3/videos/{video_id}`, never the concrete URL.
`auth_method`	`api_key`, `oauth`, `mcp` or `cli`.
`api_key`	The key used, with its name and last characters. `null` for a call made without a key.
`project`, `environment`	The key’s tags when the call was made.
`job.status`	The job’s state now: `pending`, `processing`, `completed` or `failed`. `failure_code` is set when it failed.
`charge.amount`	Charged in `charge.unit`: `credits`, or `minutes` on a video-minutes plan. `amount_usd` adds the dollar value when it is known.
`charge.refunded`	Whether any of the call’s charge was refunded.
`charge_recorded`	`true` when charges were being recorded at the time of the call, so a `null` charge means the call charged nothing.

Usage

GET /v3/usage returns what your API keys spent, per credit pool. It counts charges made with an API key, so OAuth, MCP and web usage sit outside these rows and the total can differ from your workspace balance.

curl "https://api.heygen.com/v3/usage?start_time=1761696000&end_time=1762300800&group_by=project&bucket=day" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Parameter	Description
`start_time`, `end_time`	Range, Unix seconds, counted in whole UTC days (whole UTC hours with `bucket=hour`). Up to 90 days.
`group_by`	`api_key` (default), `project`, `environment`, `product`, `endpoint` or `channel`.
`bucket`	`day` for one row per group and UTC day, `hour` for one row per group and UTC hour across up to 7 days. Omit for one row per group over the whole range.
`limit`	Groups per page, 1 to 100. Default 50.
`token`	The `next_token` of the previous page.

`group_by`	One row per
`api_key`	Key. A regenerated key and the keys it replaced share one row.
`project`, `environment`	Tag value. `""` groups untagged keys.
`product`	Product charged. `tag` is a stable identifier and `label` its display name.
`endpoint`	Route template, HTTP methods combined.
`channel`	Sign-in method: `api_key`, `mcp`, `cli` or `oauth`.

Response

{
  "data": [
    {
      "budget_group_id": null,
      "api_key": null,
      "tag": "onboarding",
      "label": null,
      "day": 1762214400,
      "hour": null,
      "recorded_since": 1758844800,
      "pools": [
        { "pool": "api", "unit": "credits", "charged": 340.0, "refunded": 12.5, "charge_count": 27 }
      ]
    }
  ],
  "has_more": false,
  "next_token": null
}

Each row lists spend per pool (api, plan_credit or generative_credit) in that pool’s unit. Read each pool on its own, since units can differ. Refunds count on the day they are made. Periods without spend have no row, and recorded_since marks when per-key recording began. Tag keys with a project and environment on the API keys page to split spend by product line or by staging and production.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Avatar Management

Voice Management

Video Translation

Lipsync

Tools

Asset Management

Batches

Webhook

Limits

Logs

Socials

For Agents

Integrations

Access

Request log

Find a call

Response

Usage

Response

​Access

​Request log

​Find a call

​Response

​Usage

​Response

Access

Request log

Find a call

Response

Usage

Response