Usage

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

string

required

Start of the date range (ISO 8601 format)

string

required

End of the date range (ISO 8601 format)

number

Optional: Filter by specific business ID

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"]
  }'

const response = await fetch('https://app.iqra.bot/api/v1/user/usage/count', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    startDate: '2026-03-01T00:00:00Z',
    endDate: '2026-03-31T23:59:59Z',
    metrics: ['callMinutes', 'apiRequests']
  })
});

const usageData = await response.json();

import requests

response = requests.post(
    'https://app.iqra.bot/api/v1/user/usage/count',
    headers={
        'Authorization': 'Token YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'startDate': '2026-03-01T00:00:00Z',
        'endDate': '2026-03-31T23:59:59Z',
        'metrics': ['callMinutes', 'apiRequests']
    }
)

usage_data = response.json()

Response

boolean

Whether the request succeeded

object

Usage count data

Show Usage metrics

number

Total call duration in minutes

number

Total API requests made

number

Characters processed by TTS

number

Minutes of STT processing

number

LLM tokens consumed

number

Embedding tokens used

object

The requested time period

Show Period details

string

Start date (ISO 8601)

string

End date (ISO 8601)

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

number

Page number (1-indexed, default: 1)

number

Number of results per page (default: 50, max: 100)

string

Filter by start date (ISO 8601)

string

Filter by end date (ISO 8601)

number

Filter by specific business

string

Filter by metric type (see available metrics above)

string

Field to sort by: timestamp, amount, businessId

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

boolean

Whether the request succeeded

object

Paginated usage history

Show Pagination structure

array

Array of usage records

Show Usage record

string

Unique record identifier

string

When the usage occurred (ISO 8601)

number

Associated business ID

string

Type of metric recorded

number

Usage amount

object

Additional context (conversation ID, provider, etc.)

object

Pagination metadata

Show properties

number

Current page number

number

Items per page

number

Total number of records

number

Total number of pages

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

Code	Description
`INVALID_DATE_RANGE`	Start date must be before end date
`DATE_RANGE_TOO_LARGE`	Date range exceeds maximum allowed (typically 90 days)
`INVALID_METRIC_TYPE`	Specified metric type is not supported
`PERMISSION_DENIED`	API 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.

User API - Retrieve user profile information
Businesses API - Manage business accounts
Conversations API - Access conversation details that contribute to usage

FlowApp System

API Reference

Advanced

Get usage count

Request

Response

Get usage history

Request

Response

Use cases

Billing dashboard

Cost tracking

Usage alerts

Business analytics

Error codes

Notes

​Get usage count

​Request

​Response

​Get usage history

​Request

​Response

​Use cases

Billing dashboard

Cost tracking

Usage alerts

Business analytics

​Error codes

​Notes

​Related endpoints

Get usage count

Request

Response

Get usage history

Request

Response

Use cases

Error codes

Notes

Related endpoints