> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zencoder.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics API

> Ingest user analytics data directly into your existing analytics platform

## Overview

The Zencoder Analytics API enables programmatic access to your organization's usage data, allowing you to integrate Zencoder metrics into your existing business intelligence tools, custom dashboards, and reporting systems. This REST API provides the same data available in the [Analytics Dashboard](/features/analytics) in a machine-readable format.

<Note>
  API access is available for users on [Pro Plus plans and above](/faq/pricing). Requires **Owner or Manager** role permissions within your organization.
</Note>

## Getting Your API Credentials

Before making API requests, you'll need to generate a personal access token to obtain your `client_id` and `client_secret`:

1. Navigate to [auth.zencoder.ai](https://auth.zencoder.ai) and sign in
2. Go to **Administration → Settings**
3. Select **Personal Tokens** from the settings menu
4. Click **Generate Token**
5. Configure your token:
   * **Description**: Enter a meaningful identifier (e.g., "Analytics API Integration" or "BI Dashboard")
   * **Expiration**: Select an appropriate duration for your use case
6. Click **Generate**

<Warning>
  **Important**: After generation, immediately copy and securely store both your **Client ID** and **Client Secret**. The Client Secret will only be displayed once and cannot be retrieved later. Store these credentials in a secure location such as a password manager or secrets management system.
</Warning>

## Authentication

To authenticate and obtain a JWT access token, make a POST request to the authentication endpoint.

**Endpoint**

```
POST https://fe.zencoder.ai/oauth/token
```

**Headers**

* `Content-Type: application/json`

**Request Body Parameters**

| Parameter       | Type   | Required | Description                                      |
| --------------- | ------ | -------- | ------------------------------------------------ |
| `client_id`     | string | Yes      | Your client identifier                           |
| `client_secret` | string | Yes      | Your client secret key                           |
| `grant_type`    | string | Yes      | OAuth 2.0 grant type. Use `"client_credentials"` |

**Using the Access Token**

Include the obtained JWT token in the `Authorization` header of subsequent API requests:

```http theme={"system"}
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

**Example Requests**

<Tabs>
  <Tab title="cURL">
    ```bash theme={"system"}
    # Get access token
    curl -X POST https://fe.zencoder.ai/oauth/token \
      -H "Content-Type: application/json" \
      -d '{
        "client_id": "your_client_id",
        "client_secret": "your_client_secret",
        "grant_type": "client_credentials"
      }'

    # Use the token in subsequent requests
    curl -X GET https://api.zencoder.ai/your-endpoint \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={"system"}
    // Get access token
    const response = await fetch('https://fe.zencoder.ai/oauth/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        client_id: 'your_client_id',
        client_secret: 'your_client_secret',
        grant_type: 'client_credentials'
      })
    });

    const { access_token } = await response.json();

    // Use the token in subsequent requests
    const usageResponse = await fetch('https://api.zencoder.ai/your-endpoint', {
      headers: {
        'Authorization': `Bearer ${access_token}`
      }
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import requests

    # Get access token
    response = requests.post(
        'https://fe.zencoder.ai/oauth/token',
        headers={'Content-Type': 'application/json'},
        json={
            'client_id': 'your_client_id',
            'client_secret': 'your_client_secret',
            'grant_type': 'client_credentials'
        }
    )

    access_token = response.json()['access_token']

    # Use the token in subsequent requests
    usage_response = requests.get(
        'https://api.zencoder.ai/your-endpoint',
        headers={'Authorization': f'Bearer {access_token}'}
    )
    ```
  </Tab>
</Tabs>

**Response**

```json theme={"system"}
{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJSU...",
  "id_token": "eyJhbGciOiJSU...",
  "refresh_token": "5bead02f-...",
  "expires_in": 86400
}
```

**Response Fields**

<AccordionGroup>
  <Accordion title="View Response Fields">
    | Field           | Type   | Description                                       |
    | --------------- | ------ | ------------------------------------------------- |
    | `token_type`    | string | Token type (e.g., "Bearer")                       |
    | `access_token`  | string | JWT token to be used in subsequent API requests   |
    | `id_token`      | string | Same as `access_token`                            |
    | `refresh_token` | string | JWT refresh token for obtaining new tokens        |
    | `expires_in`    | int    | Time until `access_token`'s expiration in seconds |
  </Accordion>
</AccordionGroup>

## Usage Data Endpoint

Retrieves usage analytics data for the authenticated tenant (account).

**Endpoint**

```
GET /api/v1/data/usage
```

**Headers**

* `Authorization: Bearer YOUR_ACCESS_TOKEN`

**Query String Parameters**

| Parameter | Type   | Required | Description                                                                                                                |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `period`  | string | No       | Time period for usage data. Must be one of: `7d`, `30d`, `90d`. Defaults to `7d` if neither `period` nor `day` is provided |
| `day`     | string | No       | Specific day for usage data in `YYYY-MM-DD` format. Cannot be used together with `period`                                  |

**Note**: You must provide either `period` OR `day`, but not both. If neither is provided, defaults to `period=7d`.

**Example Requests**

Get usage data for the last 30 days:

```http theme={"system"}
GET /api/v1/data/usage?period=30d HTTP/1.1
Host: api.zencoder.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

Get usage data for a specific day:

```http theme={"system"}
GET /api/v1/data/usage?day=2025-10-15 HTTP/1.1
Host: api.zencoder.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

**Response**

Success Response (200 OK):

```json theme={"system"}
{
  "status": "success",
  "data": {
    "period": {
      "start": "2025-09-24",
      "end": "2025-10-01",
      "days": 7
    },
    "summary": {
      "total_active_users": 48,
      "total_messages": 1372
    },
    "users": [
      {
        "email": "joe.doe@example.ai",
        "messages": 58,
        "last_active": "2025-10-01",
        "ides": [
          "VS Code"
        ],
        "languages": [
          "JavaScript",
          "TypeScript"
        ]
      }
    ],
    "daily": [
      {
        "day": "2025-09-24",
        "active_users": 21,
        "messages": 188,
        "ides": [
          {
            "ide_name": "VS Code",
            "engaged_users": 6
          },
          {
            "ide_name": "IntelliJ CE",
            "engaged_users": 1
          },
          {
            "ide_name": "WebStorm",
            "engaged_users": 1
          }
        ],
        "languages": [
          {
            "language_name": "JavaScript",
            "engaged_users": 1
          },
          {
            "language_name": "TypeScript",
            "engaged_users": 2
          }
        ]
      }
    ]
  }
}
```

Error Responses:

<AccordionGroup>
  <Accordion title="400 Bad Request - Invalid period parameter">
    ```json theme={"system"}
    {
      "status": "error",
      "message": "Invalid period parameter. Period has to be one of 7d, 30d, 90d"
    }
    ```
  </Accordion>

  <Accordion title="400 Bad Request - Invalid day parameter format">
    ```json theme={"system"}
    {
      "status": "error",
      "message": "Invalid day parameter. Day must be in YYYY-MM-DD format"
    }
    ```
  </Accordion>

  <Accordion title="400 Bad Request - Both period and day parameters provided">
    ```json theme={"system"}
    {
      "status": "error",
      "message": "Only one parameter is expected. Provide either 'day' or 'period', not both"
    }
    ```
  </Accordion>

  <Accordion title="500 Internal Server Error">
    ```json theme={"system"}
    {
      "status": "error",
      "message": "Failed to fetch data"
    }
    ```
  </Accordion>
</AccordionGroup>

**Response Fields**

<AccordionGroup>
  <Accordion title="Data Object">
    | Field     | Type   | Description                          |
    | --------- | ------ | ------------------------------------ |
    | `period`  | object | Time period information for the data |
    | `summary` | object | Aggregate statistics for the period  |
    | `users`   | array  | List of user usage details           |
    | `daily`   | array  | Daily breakdown of usage statistics  |
  </Accordion>

  <Accordion title="Period Object">
    | Field   | Type   | Description                                |
    | ------- | ------ | ------------------------------------------ |
    | `start` | string | Start date of the period (ISO 8601 format) |
    | `end`   | string | End date of the period (ISO 8601 format)   |
    | `days`  | int    | Number of days in the period               |
  </Accordion>

  <Accordion title="Summary Object">
    | Field                | Type | Description                                 |
    | -------------------- | ---- | ------------------------------------------- |
    | `total_active_users` | int  | Total number of active users in the period  |
    | `total_messages`     | int  | Total number of messages sent in the period |
  </Accordion>

  <Accordion title="User Object">
    | Field         | Type   | Description                                    |
    | ------------- | ------ | ---------------------------------------------- |
    | `email`       | string | User's email address                           |
    | `messages`    | int    | Number of messages sent by the user            |
    | `last_active` | string | Date of user's last activity (ISO 8601 format) |
    | `ides`        | array  | List of IDEs used by the user                  |
    | `languages`   | array  | List of programming languages used             |
  </Accordion>

  <Accordion title="Daily Data Object">
    | Field          | Type   | Description                                |
    | -------------- | ------ | ------------------------------------------ |
    | `day`          | string | Date for this data point (ISO 8601 format) |
    | `active_users` | int    | Number of active users on this day         |
    | `messages`     | int    | Number of messages sent on this day        |
    | `ides`         | array  | IDE usage breakdown for this day           |
    | `languages`    | array  | Language usage breakdown for this day      |
  </Accordion>

  <Accordion title="IDE Usage Object">
    | Field           | Type   | Description                       |
    | --------------- | ------ | --------------------------------- |
    | `ide_name`      | string | Name of the IDE                   |
    | `engaged_users` | int    | Number of users who used this IDE |
  </Accordion>

  <Accordion title="Language Usage Object">
    | Field           | Type   | Description                            |
    | --------------- | ------ | -------------------------------------- |
    | `language_name` | string | Name of the programming language       |
    | `engaged_users` | int    | Number of users who used this language |
  </Accordion>
</AccordionGroup>

**Example Requests**

<Tabs>
  <Tab title="Last 30 Days">
    <Tabs>
      <Tab title="cURL">
        ```bash theme={"system"}
        curl -X GET "https://api.zencoder.ai/api/v1/data/usage?period=30d" \
          -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
        ```
      </Tab>

      <Tab title="Node.js">
        ```javascript theme={"system"}
        const response = await fetch('https://api.zencoder.ai/api/v1/data/usage?period=30d', {
          headers: {
            'Authorization': `Bearer ${access_token}`
          }
        });
        const data = await response.json();
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={"system"}
        response = requests.get(
            'https://api.zencoder.ai/api/v1/data/usage?period=30d',
            headers={'Authorization': f'Bearer {access_token}'}
        )
        data = response.json()
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Specific Day">
    <Tabs>
      <Tab title="cURL">
        ```bash theme={"system"}
        curl -X GET "https://api.zencoder.ai/api/v1/data/usage?day=2025-10-15" \
          -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
        ```
      </Tab>

      <Tab title="Node.js">
        ```javascript theme={"system"}
        const response = await fetch('https://api.zencoder.ai/api/v1/data/usage?day=2025-10-15', {
          headers: {
            'Authorization': `Bearer ${access_token}`
          }
        });
        const data = await response.json();
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={"system"}
        response = requests.get(
            'https://api.zencoder.ai/api/v1/data/usage?day=2025-10-15',
            headers={'Authorization': f'Bearer {access_token}'}
        )
        data = response.json()
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Last 7 Days (Default)">
    <Tabs>
      <Tab title="cURL">
        ```bash theme={"system"}
        curl -X GET "https://api.zencoder.ai/api/v1/data/usage" \
          -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
        ```
      </Tab>

      <Tab title="Node.js">
        ```javascript theme={"system"}
        const response = await fetch('https://api.zencoder.ai/api/v1/data/usage', {
          headers: {
            'Authorization': `Bearer ${access_token}`
          }
        });
        const data = await response.json();
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={"system"}
        response = requests.get(
            'https://api.zencoder.ai/api/v1/data/usage',
            headers={'Authorization': f'Bearer {access_token}'}
        )
        data = response.json()
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication Failures">
    * Verify your `client_id` and `client_secret` are correct
    * Ensure your subscription is Core or higher
    * Check that your account has Owner or Manager permissions
    * Confirm you generated a personal access token in Settings
  </Accordion>

  <Accordion title="401 Unauthorized Errors">
    * Confirm your access token hasn't expired (24-hour lifetime)
    * Verify the token is included in the `Authorization` header with `Bearer` prefix
    * Request a new token if the current one has expired
  </Accordion>

  <Accordion title="Empty or Missing Data">
    * Confirm users in your organization have been active during the requested period
    * Verify the date format for `day` parameter is `YYYY-MM-DD`
    * Check that the requested date range contains activity
    * Ensure users are part of your organization and have authenticated at least once
  </Accordion>

  <Accordion title="Invalid Parameter Errors">
    * For `period` parameter, use only: `7d`, `30d`, or `90d`
    * For `day` parameter, use format: `YYYY-MM-DD`
    * Do not provide both `period` and `day` parameters in the same request
  </Accordion>

  <Accordion title="Connection or Network Issues">
    * Verify you can reach `https://fe.zencoder.ai` and `https://api.zencoder.ai`
    * Check your firewall or proxy settings
    * Ensure your network allows HTTPS requests to Zencoder endpoints
  </Accordion>
</AccordionGroup>