> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/abdofallah/IqraAI/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Track usage metrics, billing information, and consumption history

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.

```bash theme={null}
POST /api/v1/user/usage/count
```

This endpoint returns summary statistics for your usage across all metrics.

### Request

<ParamField body="startDate" type="string" required>
  Start of the date range (ISO 8601 format)
</ParamField>

<ParamField body="endDate" type="string" required>
  End of the date range (ISO 8601 format)
</ParamField>

<ParamField body="businessId" type="number">
  Optional: Filter by specific business ID
</ParamField>

<ParamField body="metrics" type="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
</ParamField>

**Example request:**

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

### Response

<ResponseField name="success" type="boolean">
  Whether the request succeeded
</ResponseField>

<ResponseField name="data" type="object">
  Usage count data

  <Expandable title="Usage metrics">
    <ResponseField name="callMinutes" type="number">
      Total call duration in minutes
    </ResponseField>

    <ResponseField name="apiRequests" type="number">
      Total API requests made
    </ResponseField>

    <ResponseField name="ttsCharacters" type="number">
      Characters processed by TTS
    </ResponseField>

    <ResponseField name="sttMinutes" type="number">
      Minutes of STT processing
    </ResponseField>

    <ResponseField name="llmTokens" type="number">
      LLM tokens consumed
    </ResponseField>

    <ResponseField name="embeddingTokens" type="number">
      Embedding tokens used
    </ResponseField>

    <ResponseField name="period" type="object">
      The requested time period

      <Expandable title="Period details">
        <ResponseField name="start" type="string">
          Start date (ISO 8601)
        </ResponseField>

        <ResponseField name="end" type="string">
          End date (ISO 8601)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

**Example response:**

```json theme={null}
{
  "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.

```bash theme={null}
POST /api/v1/user/usage/history
```

This endpoint returns individual usage records for granular analysis.

### Request

<ParamField body="page" type="number">
  Page number (1-indexed, default: 1)
</ParamField>

<ParamField body="pageSize" type="number">
  Number of results per page (default: 50, max: 100)
</ParamField>

<ParamField body="startDate" type="string">
  Filter by start date (ISO 8601)
</ParamField>

<ParamField body="endDate" type="string">
  Filter by end date (ISO 8601)
</ParamField>

<ParamField body="businessId" type="number">
  Filter by specific business
</ParamField>

<ParamField body="metricType" type="string">
  Filter by metric type (see available metrics above)
</ParamField>

<ParamField body="sortBy" type="string">
  Field to sort by: `timestamp`, `amount`, `businessId`
</ParamField>

<ParamField body="sortOrder" type="string">
  Sort direction: `asc` or `desc`
</ParamField>

**Example request:**

```bash theme={null}
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

<ResponseField name="success" type="boolean">
  Whether the request succeeded
</ResponseField>

<ResponseField name="data" type="object">
  Paginated usage history

  <Expandable title="Pagination structure">
    <ResponseField name="items" type="array">
      Array of usage records

      <Expandable title="Usage record">
        <ResponseField name="id" type="string">
          Unique record identifier
        </ResponseField>

        <ResponseField name="timestamp" type="string">
          When the usage occurred (ISO 8601)
        </ResponseField>

        <ResponseField name="businessId" type="number">
          Associated business ID
        </ResponseField>

        <ResponseField name="metricType" type="string">
          Type of metric recorded
        </ResponseField>

        <ResponseField name="amount" type="number">
          Usage amount
        </ResponseField>

        <ResponseField name="metadata" type="object">
          Additional context (conversation ID, provider, etc.)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="pagination" type="object">
      Pagination metadata

      <Expandable title="properties">
        <ResponseField name="page" type="number">
          Current page number
        </ResponseField>

        <ResponseField name="pageSize" type="number">
          Items per page
        </ResponseField>

        <ResponseField name="totalItems" type="number">
          Total number of records
        </ResponseField>

        <ResponseField name="totalPages" type="number">
          Total number of pages
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

**Example response:**

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Billing dashboard" icon="chart-bar">
    Display usage metrics and consumption trends
  </Card>

  <Card title="Cost tracking" icon="dollar-sign">
    Monitor usage to estimate costs and budget
  </Card>

  <Card title="Usage alerts" icon="bell">
    Set up alerts when usage exceeds thresholds
  </Card>

  <Card title="Business analytics" icon="chart-line">
    Analyze usage patterns across businesses
  </Card>
</CardGroup>

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

<Note>
  Usage data is updated in near real-time but may have a delay of up to 5 minutes for recent activity.
</Note>

<Tip>
  For large date ranges, use the `count` endpoint for aggregated data and `history` for detailed breakdowns.
</Tip>

<Warning>
  Historical usage data is retained for 12 months. Older records may not be available.
</Warning>

## Related endpoints

* [User API](/api/user) - Retrieve user profile information
* [Businesses API](/api/businesses) - Manage business accounts
* [Conversations API](/api/conversations) - Access conversation details that contribute to usage