Request Logs

Read your workspace’s API request log and per-key spend over the API: every write call with its status, error code, job and charge, and spend grouped by key, project, environment, product, endpoint or channel.

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.