Source: https://datafa.st/docs/api/website/bot-traffic/usage
Markdown source: https://datafa.st/docs/api/website/bot-traffic/usage.md
Description: Return the account-wide Bot traffic allowance shown on the billing page: accepted usage, dropped requests after the limit, remaining capacity, paid packs, billing-cycle dates, and usage by website.

# Get account Bot traffic usage

`GET https://datafa.st/api/v1/admin/bot-traffic/usage`

Return the account-wide Bot traffic allowance shown on the billing page: accepted usage, dropped requests after the limit, remaining capacity, paid packs, billing-cycle dates, and usage by website.

MCP equivalent: `datafast_bot_traffic_usage`. This endpoint reports capacity but never purchases it or charges a payment method; capacity changes remain a human-confirmed action in Billing.

> **Related:** [Bot traffic API](/docs/api/website/bot-traffic) · [Billing](/dashboard/billing)

## Request

This endpoint does not require any path, query, or body parameters.

## Response

Returns a JSON object with `status: "success"` and endpoint-specific fields in `data` (and `pagination` when the endpoint is paginated).

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `data[].usage.usage` | number | Accepted requests in the current allowance period. |
| `data[].usage.dropped` | number | Eligible requests not recorded after capacity was exhausted. |
| `data[].usage.allowance` | number | Included and paid request capacity combined. |
| `data[].usage.remaining` | number | Unused requests in the current period. |
| `data[].usage.percentUsed` | number | Usage as a percentage of allowance, capped at 100. |
| `data[].usage.periodStartAt` | string | Current billing-cycle usage start. |
| `data[].usage.resetAt` | string | When usage resets to zero. |
| `data[].usage.isCounting` | boolean | Whether allowance counting is active. |
| `data[].websiteStats[]` | array | Only websites with usage, including website ID, domain, logo, and request count. |
| `data[].billing` | object | Add-on status, pack quantity, scheduled change, price, and billing-cycle state. |
| `data[].includedRequests` | number | Free requests included per billing cycle. |
| `data[].packRequests` | number | Requests included in each paid pack. |
| `data[].packMonthlyPrice` | number | Monthly price in USD for one pack. |
| `data[].canView` | boolean | Whether the account can view Bot traffic capacity. |
| `data[].canPurchase` | boolean | Whether the account can purchase or change capacity. |

## Authentication

Requires an owner `dft_` account token with `analytics:read`. Website API keys (`df_`) cannot call this endpoint.

The token must have access to all websites on the account (`websiteIds: []`) because Bot traffic allowance is account-wide.

The account must have active DataFast API access. Read [authentication and scopes](/docs/api/authentication) for token creation and permissions.

### Errors

**403** — The token is website-scoped, lacks `analytics:read`, or the account has no API access.

**404** — Account not found.

**503** — Usage is temporarily unavailable.

See [API errors](/docs/api#errors) for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

## Code examples

### Example request

```bash
curl -X GET "https://datafa.st/api/v1/admin/bot-traffic/usage" \
  -H "Authorization: Bearer dft_xxx"
```

### Success response

```json
{
  "status": "success",
  "data": [{
    "usage": {
      "usage": 81240,
      "dropped": 0,
      "packQuantity": 0,
      "allowance": 100000,
      "remaining": 18760,
      "percentUsed": 81.24,
      "periodStartAt": "2026-09-15T00:00:00.000Z",
      "resetAt": "2026-10-15T00:00:00.000Z",
      "isCounting": true
    },
    "websiteStats": [{
      "websiteId": "665f0b3c4d2e1a0012345678",
      "domain": "example.com",
      "logo": null,
      "requestCount": 81240
    }],
    "includedRequests": 100000,
    "packRequests": 1000000,
    "packMonthlyPrice": 9,
    "canView": true,
    "canPurchase": true
  }]
}
```