---
title: "Get API key statistics"
canonical_url: https://docs.zvid.io/docs/endpoints/get-api-key-stats/
source: docs/endpoints/get-api-key-stats.api.mdx
content_revision: 6338386a1dd87e4a
---

# Get API key statistics

`GET /api/api-keys/{id}/stats`

Retrieve usage statistics for a specific API key, based on audit logs, for a given timeframe

## Authentication

- Option 1: `x-api-key: YOUR_API_KEY` (header). API key for authentication. Create one in your dashboard.
- Option 2: `Authorization: Bearer YOUR_ACCESS_TOKEN`. Dashboard JWT in Authorization: Bearer <token>, only on operations that explicitly list this scheme. Prefer x-api-key for REST integrations. OAuth for hosted MCP is a separate connection at https://mcp.zvid.io/mcp.

Create API keys at [app.zvid.io/api-keys](https://app.zvid.io/api-keys). Keep credentials on your server.

## Parameters

| Parameter | Location | Type | Required | Description and constraints |
| --- | --- | --- | --- | --- |
| `id` | path | integer | Yes | API key ID |
| `timeframe` | query | `"24h"` / `"7d"` / `"30d"` | No | Timeframe for statistics. Supported values: 24h, 7d, 30d (default: 30d). Default: `"30d"`. |

## Request

The shell examples read credentials from `ZVID_API_KEY` (or `ZVID_ACCESS_TOKEN` for Bearer authentication). Set that variable in your environment. Replace sample project, template, job, and asset identifiers with values from your own account.

This operation does not take a request body.

### Request example

```bash
curl --request GET 'https://api.zvid.io/api/api-keys/789/stats' \
  --header "x-api-key: $ZVID_API_KEY"
```

## Responses


### HTTP 200

API key statistics retrieved successfully

Content type: `application/json`.

Unknown properties are rejected. Required properties: `timeframe`, `summary`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.timeframe` | `"24h"` / `"7d"` / `"30d"` | Yes |  |
| `response.summary` | object | Yes | Aggregated statistics for the selected timeframe Unknown properties are rejected. Required properties: `totalRequests`, `successfulRequests`, `failedRequests`. |
| `response.dailyStats` | array of object | No | Daily request breakdown over the last 30 days |

**Nested field: `response.summary`**

Aggregated statistics for the selected timeframe

Unknown properties are rejected. Required properties: `totalRequests`, `successfulRequests`, `failedRequests`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.summary.totalRequests` | integer | Yes |  |
| `response.summary.successfulRequests` | integer | Yes |  |
| `response.summary.failedRequests` | integer | Yes |  |
| `response.summary.avgResponseTime` | number | No |  |

**Nested field: `response.dailyStats`**

Daily request breakdown over the last 30 days

**Array item: `response.dailyStats[]`**

Unknown properties are rejected. Required properties: `date`, `requests`, `successful`, `failed`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.dailyStats[].date` | string | Yes | Format: `date`. |
| `response.dailyStats[].requests` | integer | Yes |  |
| `response.dailyStats[].successful` | integer | Yes |  |
| `response.dailyStats[].failed` | integer | Yes |  |


**Example response**

```json
{
  "timeframe": "30d",
  "summary": {
    "totalRequests": 1500,
    "successfulRequests": 1400,
    "failedRequests": 100,
    "avgResponseTime": 120.5
  },
  "dailyStats": [
    {
      "date": "2025-01-01",
      "requests": 50,
      "successful": 48,
      "failed": 2
    },
    {
      "date": "2025-01-02",
      "requests": 75,
      "successful": 70,
      "failed": 5
    }
  ]
}
```

### HTTP 401

Unauthorized

Content type: `application/json`.

Unknown properties are rejected. Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes | Error type |
| `response.message` | string | No | Human-readable error message |


### HTTP 500

Internal server error

Content type: `application/json`.

Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes | Error type |
| `response.message` | string | No | Human-readable error message |


## Schema definitions

The following definitions describe the fields referenced above. Expand a definition to inspect its complete contract.


### schema api key stats

**ApiKeyStats**


Unknown properties are rejected. Required properties: `timeframe`, `summary`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `ApiKeyStats.timeframe` | `"24h"` / `"7d"` / `"30d"` | Yes |  |
| `ApiKeyStats.summary` | object | Yes | Aggregated statistics for the selected timeframe Unknown properties are rejected. Required properties: `totalRequests`, `successfulRequests`, `failedRequests`. |
| `ApiKeyStats.dailyStats` | array of object | No | Daily request breakdown over the last 30 days |

**Nested field: `ApiKeyStats.summary`**

Aggregated statistics for the selected timeframe

Unknown properties are rejected. Required properties: `totalRequests`, `successfulRequests`, `failedRequests`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `ApiKeyStats.summary.totalRequests` | integer | Yes |  |
| `ApiKeyStats.summary.successfulRequests` | integer | Yes |  |
| `ApiKeyStats.summary.failedRequests` | integer | Yes |  |
| `ApiKeyStats.summary.avgResponseTime` | number | No |  |

**Nested field: `ApiKeyStats.dailyStats`**

Daily request breakdown over the last 30 days

**Array item: `ApiKeyStats.dailyStats[]`**

Unknown properties are rejected. Required properties: `date`, `requests`, `successful`, `failed`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `ApiKeyStats.dailyStats[].date` | string | Yes | Format: `date`. |
| `ApiKeyStats.dailyStats[].requests` | integer | Yes |  |
| `ApiKeyStats.dailyStats[].successful` | integer | Yes |  |
| `ApiKeyStats.dailyStats[].failed` | integer | Yes |  |


### schema authentication error

**AuthenticationError**


Unknown properties are rejected. Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `AuthenticationError.error` | string | Yes | Error type |
| `AuthenticationError.message` | string | No | Human-readable error message |


### schema error

**Error**


Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `Error.error` | string | Yes | Error type |
| `Error.message` | string | No | Human-readable error message |


## Related resources

- [OpenAPI specification](https://docs.zvid.io/openapi.yaml)
- [Project payload schema](https://docs.zvid.io/schemas/render-payload.schema.json)
- [Quick Start](https://docs.zvid.io/docs/quick-start/)
- [Authentication guide](https://docs.zvid.io/docs/authentication/)