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 in a machine-readable format.

API access is available for users on Core plans and above. Requires Owner or Manager role permissions within your organization.

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

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.

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:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Requests

cURL

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

Response

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJSU...",
  "id_token": "eyJhbGciOiJSU...",
  "refresh_token": "5bead02f-...",
  "expires_in": 86400
}

Response Fields

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

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:

GET /api/v1/data/usage?period=30d HTTP/1.1
Host: api.zencoder.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Get usage data for a specific day:

GET /api/v1/data/usage?day=2025-10-15 HTTP/1.1
Host: api.zencoder.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "period": {
      "start": "2025-09-24",
      "end": "2025-10-01",
      "days": 7
    },
    "summary": {
      "total_active_users": 48,
      "total_messages": 1372
    },
    "users": [
      {
        "email": "[e-mail]",
        "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:

400 Bad Request - Invalid period parameter

{
  "status": "error",
  "message": "Invalid period parameter. Period has to be one of 7d, 30d, 90d"
}

400 Bad Request - Invalid day parameter format

{
  "status": "error",
  "message": "Invalid day parameter. Day must be in YYYY-MM-DD format"
}

400 Bad Request - Both period and day parameters provided

{
  "status": "error",
  "message": "Only one parameter is expected. Provide either 'day' or 'period', not both"
}

500 Internal Server Error

{
  "status": "error",
  "message": "Failed to fetch data"
}

Response Fields

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

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

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

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

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

IDE Usage Object

Field	Type	Description
ide_name	string	Name of the IDE
engaged_users	int	Number of users who used this IDE

Language Usage Object

Field	Type	Description
language_name	string	Name of the programming language
engaged_users	int	Number of users who used this language

Example Requests

Last 30 Days

cURL

curl -X GET "https://api.zencoder.ai/api/v1/data/usage?period=30d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Troubleshooting

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

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

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

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

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