> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-4.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=ed7eea7e860c769f9b1b12804a27315a)

Two read endpoints return the data behind the [Logs](https://platform.heygen.com/logs) and [Usage](https://platform.heygen.com/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](https://heygen-1fa696a7.mintlify.site/docs/api-key.md) or an OAuth token. A restricted key needs the `usage:read` [scope](https://heygen-1fa696a7.mintlify.site/docs/api-key-permissions.md).
* 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.

```bash theme={null}
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](https://heygen-1fa696a7.mintlify.site/docs/error-codes.md) 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

```json theme={null}
{
  "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.

```bash theme={null}
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

```json theme={null}
{
  "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](https://platform.heygen.com/api-keys) to split spend by product line or by staging and production.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.