The Reporting API lets you query your ad performance data programmatically. Use it to build custom dashboards, automate reports, or feed data into your analytics pipeline.
Before You Start
- You need a Publisher Dashboard account with access to the Reporting API section.
- Credentials are created per publisher. Anyone on your team with dashboard access can enable it.
- Keep your
client_secret safe — it is only shown once and cannot be recovered.
Step 1 — Enable the Reporting API
Log in to the Publisher Dashboard
Navigate to your Publisher Dashboard and sign in.
Open the Reporting API section
In the left navigation, click Reporting API.
Enable access
Toggle the switch from Disabled to Enabled. A credentials panel appears showing your Client ID and Client Secret.Copy and store both values somewhere secure (a password manager, secrets vault, or environment variable).The client secret is shown only once and cannot be recovered. If you lose it, you must rotate your credentials.
Need to rotate credentials? Disable and re-enable the Reporting API. A new Client ID and Client Secret are generated. Any active integrations using the old credentials will stop working immediately — update them before rotating.
Step 2 — Get an Access Token
Every API request requires a short-lived access token. Tokens expire after 15 minutes — your integration should request a new one when the current token is close to expiry.
POST https://api.vlc.io/api/public/v1/token
Content-Type: application/json
{
"grant_type": "client_credentials",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 900
}
expires_in is in seconds (900 = 15 minutes). Use the access_token in all subsequent requests.
Step 3 — Query Reporting Data
With a valid token, query the reporting endpoint. Pass the token in the Authorization header.
GET https://api.vlc.io/api/public/v1/reporting
Authorization: Bearer YOUR_ACCESS_TOKEN
Query Parameters
| Parameter | Required | Description | Example |
|---|
dateFrom | Yes | Start of date range (inclusive), YYYY-MM-DD | 2026-01-01 |
dateTo | Yes | End of date range (inclusive), YYYY-MM-DD | 2026-01-31 |
breakBy | No | Comma-separated dimensions to group results by | date,country |
metrics | No | Comma-separated metrics to include | revenue,impressions |
page | No | Page number for paginated results (default: 1) | 2 |
perPage | No | Rows per page (default: 10) | 100 |
Example Request
GET https://api.vlc.io/api/public/v1/reporting?dateFrom=2026-01-01&dateTo=2026-01-31&breakBy=date,country&metrics=revenue,impressions
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Response
{
"data": [
{
"date": "2026-01-01",
"country": "US",
"revenue": 123.45,
"impressions": 10000
},
{
"date": "2026-01-01",
"country": "GB",
"revenue": 67.89,
"impressions": 5000
}
],
"total": 62,
"page": 1,
"perPage": 10
}
total is the total number of rows across all pages. Use page and perPage to paginate through large result sets.
Full Example (cURL)
# Step 1: Exchange credentials for an access token
TOKEN=$(curl -s -X POST https://api.vlc.io/api/public/v1/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}' | jq -r .access_token)
# Step 2: Query reporting data
curl -H "Authorization: Bearer $TOKEN" \
"https://api.vlc.io/api/public/v1/reporting?dateFrom=2026-01-01&dateTo=2026-01-31&breakBy=date,country&metrics=revenue,impressions"
Rate Limits
| Endpoint | Limit |
|---|
POST /api/public/v1/token | 10 requests/minute |
GET /api/public/v1/reporting | 100 requests/minute |
429 Too Many Requests. Wait until the next minute window before retrying.
Error Reference
| HTTP Status | Meaning |
|---|
400 | Bad request — check your request body or query parameters |
401 | Unauthorized — the token is missing, expired, or invalid |
429 | Too many requests — slow down and retry after a short wait |
500 | Server error — something went wrong on our end; try again shortly |
Security Best Practices
- Never expose your
client_secret in client-side code, browser extensions, or public repositories.
- Store credentials in environment variables or a secrets manager, not in source code.
- Tokens are short-lived (15 minutes) — your integration should handle re-authentication automatically.
- If you suspect your credentials have been compromised, disable the Reporting API in the dashboard immediately to revoke access, then re-enable to generate new credentials.
