Usage Statistics
Monitor API usage across all credentials. Use this for billing, analytics, and identifying high-usage integrations.
Permission Required
Requires the view_usage permission.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/admin/usage | Usage summary for all credentials |
| GET | /v1/admin/usage/:id | Detailed usage for a specific credential |
Usage Summary
Get aggregated usage statistics for all credentials.
Request
http
GET /v1/admin/usage
Authorization: Bearer {admin_key}Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 20 | Results per page (1-100) |
offset | integer | 0 | Pagination offset |
start_date | ISO 8601 | - | Filter usage from this date |
end_date | ISO 8601 | - | Filter usage until this date |
Example Request
Get all credentials usage:
bash
curl -X GET "https://api.insight.iagon.com/v1/admin/usage" \
-H "Authorization: Bearer YOUR_ADMIN_KEY"Get usage for January 2026:
bash
curl -X GET "https://api.insight.iagon.com/v1/admin/usage?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Bearer YOUR_ADMIN_KEY"Response (200 OK)
json
{
"success": true,
"data": [
{
"credential_id": "660e8400-e29b-41d4-a716-446655440001",
"credential_name": "Acme Production Key",
"api_key_prefix": "iiak_a1b2c3d4",
"user_account_id": "550e8400-e29b-41d4-a716-446655440000",
"user_account_name": "Acme Corp",
"total_requests": 15420,
"successful_requests": 15200,
"failed_requests": 220,
"last_used_at": "2026-01-26T15:30:00Z"
},
{
"credential_id": "660e8400-e29b-41d4-a716-446655440002",
"credential_name": "Acme Staging Key",
"api_key_prefix": "iiak_b2c3d4e5",
"user_account_id": "550e8400-e29b-41d4-a716-446655440000",
"user_account_name": "Acme Corp",
"total_requests": 3250,
"successful_requests": 3200,
"failed_requests": 50,
"last_used_at": "2026-01-26T14:00:00Z"
}
],
"pagination": {
"limit": 20,
"offset": 0,
"total": 45
}
}Credential Usage
Get detailed usage statistics and daily breakdown for a specific credential.
Request
http
GET /v1/admin/usage/:id
Authorization: Bearer {admin_key}Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | UUID | Credential ID |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
start_date | ISO 8601 | - | Filter usage from this date |
end_date | ISO 8601 | - | Filter usage until this date |
Example Request
Get usage for a specific credential:
bash
curl -X GET "https://api.insight.iagon.com/v1/admin/usage/660e8400-e29b-41d4-a716-446655440001" \
-H "Authorization: Bearer YOUR_ADMIN_KEY"Get last 7 days of usage:
bash
curl -X GET "https://api.insight.iagon.com/v1/admin/usage/660e8400-e29b-41d4-a716-446655440001?start_date=2026-01-19&end_date=2026-01-26" \
-H "Authorization: Bearer YOUR_ADMIN_KEY"Response (200 OK)
json
{
"success": true,
"data": {
"summary": {
"credential_id": "660e8400-e29b-41d4-a716-446655440001",
"credential_name": "Acme Production Key",
"api_key_prefix": "iiak_a1b2c3d4",
"user_account_id": "550e8400-e29b-41d4-a716-446655440000",
"user_account_name": "Acme Corp",
"total_requests": 15420,
"successful_requests": 15200,
"failed_requests": 220,
"period_start": "2026-01-01T00:00:00Z",
"period_end": "2026-01-26T23:59:59Z"
},
"daily": [
{
"date": "2026-01-26",
"total_requests": 520,
"successful_requests": 515,
"failed_requests": 5
},
{
"date": "2026-01-25",
"total_requests": 480,
"successful_requests": 478,
"failed_requests": 2
},
{
"date": "2026-01-24",
"total_requests": 510,
"successful_requests": 505,
"failed_requests": 5
}
]
}
}Error Responses
400 Bad Request - Invalid credential ID:
json
{
"success": false,
"error": "Invalid credential ID format"
}400 Bad Request - Invalid date format:
json
{
"success": false,
"error": "Invalid start_date format"
}404 Not Found - Credential not found:
json
{
"success": false,
"error": "Credential not found"
}User Account Usage
For user-level usage aggregation (combining all credentials for a user), see:
- User Usage - Usage for a specific user
- All Users Usage Summary - Usage across all users
Use Cases
Monthly Billing Report
Generate usage for billing period:
bash
curl -X GET "https://api.insight.iagon.com/v1/admin/usage?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Bearer YOUR_ADMIN_KEY"Identify High-Usage Credentials
Find your most active integrations by reviewing the usage summary sorted by total requests.
Debug Failed Requests
Check the failed_requests count to identify credentials with high error rates, which may indicate integration issues.