Skip to main content
The Usage API provides access to detailed usage metrics and billing information for the authenticated user. Track call minutes, API requests, and other consumption data across all your businesses.

​
Get usage count

Retrieve aggregated usage counts for a specific time period. 
POST /api/v1/user/usage/count
This endpoint returns summary statistics for your usage across all metrics.

​
Request

​
startDate
string
required
Start of the date range (ISO 8601 format)
​
endDate
string
required
End of the date range (ISO 8601 format)
​
businessId
number
Optional: Filter by specific business ID
​
metrics
array
Optional: Specific metrics to retrieve. Defaults to all metrics.Available metrics:
  • callMinutes - Total call duration in minutes
  • apiRequests - Number of API requests made
  • ttsCharacters - Characters sent to TTS providers
  • sttMinutes - Minutes of STT processing
  • llmTokens - LLM tokens consumed
  • embeddingTokens - Embedding tokens used
Example request: 
curl -X POST https://app.iqra.bot/api/v1/user/usage/count \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-03-01T00:00:00Z",
    "endDate": "2026-03-31T23:59:59Z",
    "metrics": ["callMinutes", "apiRequests"]
  }'

​
Response

​
success
boolean
Whether the request succeeded
​
data
object
Usage count data
Example response: 
{
  "success": true,
  "data": {
    "callMinutes": 1247.5,
    "apiRequests": 3421,
    "ttsCharacters": 245890,
    "sttMinutes": 1180.2,
    "llmTokens": 892340,
    "embeddingTokens": 124500,
    "period": {
      "start": "2026-03-01T00:00:00Z",
      "end": "2026-03-31T23:59:59Z"
    }
  }
}

​
Get usage history

Retrieve detailed usage records with pagination and filtering. 
POST /api/v1/user/usage/history
This endpoint returns individual usage records for granular analysis.

​
Request

​
page
number
Page number (1-indexed, default: 1)
​
pageSize
number
Number of results per page (default: 50, max: 100)
​
startDate
string
Filter by start date (ISO 8601)
​
endDate
string
Filter by end date (ISO 8601)
​
businessId
number
Filter by specific business
​
metricType
string
Filter by metric type (see available metrics above)
​
sortBy
string
Field to sort by: timestamp, amount, businessId
​
sortOrder
string
Sort direction: asc or desc
Example request: 
curl -X POST https://app.iqra.bot/api/v1/user/usage/history \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "pageSize": 50,
    "startDate": "2026-03-01T00:00:00Z",
    "endDate": "2026-03-31T23:59:59Z",
    "sortBy": "timestamp",
    "sortOrder": "desc"
  }'

​
Response

​
success
boolean
Whether the request succeeded
​
data
object
Paginated usage history
Example response: 
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "usage_xyz789",
        "timestamp": "2026-03-15T14:32:10Z",
        "businessId": 12345,
        "metricType": "callMinutes",
        "amount": 12.5,
        "metadata": {
          "conversationId": "conv_abc123",
          "agentId": "agent_def456"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "totalItems": 1523,
      "totalPages": 31
    }
  }
}

​
Use cases

Billing dashboard

Display usage metrics and consumption trends

Cost tracking

Monitor usage to estimate costs and budget

Usage alerts

Set up alerts when usage exceeds thresholds

Business analytics

Analyze usage patterns across businesses

​
Error codes

CodeDescription
INVALID_DATE_RANGEStart date must be before end date
DATE_RANGE_TOO_LARGEDate range exceeds maximum allowed (typically 90 days)
INVALID_METRIC_TYPESpecified metric type is not supported
PERMISSION_DENIEDAPI key lacks required permissions

​
Notes

Usage data is updated in near real-time but may have a delay of up to 5 minutes for recent activity.
For large date ranges, use the count endpoint for aggregated data and history for detailed breakdowns.
Historical usage data is retained for 12 months. Older records may not be available.

Build docs developers (and LLMs) love

Get started for freeTalk to us