> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1eye.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Retrieve monthly and daily activity counts and credits consumed for your workspace.

Retrieve monthly activity counts, credits consumed, and daily breakdowns for the workspace associated with your API key. Usage reports activities and credit consumption; [Billing](https://docs.1eye.ai/api-reference/billing.md) reports balances, money, payment methods, and invoices.

```text theme={null}
GET /v1/usage
```

## Authentication

All requests require a workspace API key:

```http theme={null}
Authorization: Bearer 1eye_live_xxxxxxxxx
```

The examples use `$API_KEY` for your API key. The key determines the workspace; you do not supply a workspace ID. See [Authentication](https://docs.1eye.ai/api-reference/auth.md).

## Query parameter

| Parameter | Type | Description |
| - | - | - |
| `month` | string | Optional reporting month in `YYYY-MM` format. Defaults to the current calendar month. |

No other query parameters, pagination, or sorting are supported.

## Request

Current month:

```bash theme={null}
curl "https://api.1eye.ai/v1/usage" \
  -H "Authorization: Bearer $API_KEY"
```

Historical month:

```bash theme={null}
curl "https://api.1eye.ai/v1/usage?month=2026-09" \
  -H "Authorization: Bearer $API_KEY"
```

## Response

**200 OK** — returns the Usage object directly.

The complete fictional example below is a snapshot taken on **October 1, 2026**, so its current-month daily array contains one applicable date. The example pricing and quantities do not prescribe workspace defaults.

```json theme={null}
{
  "client_id": "wor_123456789012345678",
  "month": "2026-10",
  "available_months": {
    "from": "2026-04",
    "to": "2026-10"
  },
  "credit_costs": {
    "buyer": 2,
    "signal": 1,
    "email": 2,
    "phone": 5
  },
  "monthly": {
    "credits_consumed": 145,
    "breakdown": {
      "buyer": {
        "count": 50,
        "credits_consumed": 100
      },
      "signal": {
        "count": 15,
        "credits_consumed": 15
      },
      "email": {
        "count": 10,
        "credits_consumed": 20
      },
      "phone": {
        "count": 2,
        "credits_consumed": 10
      }
    }
  },
  "daily": [
    {
      "date": "2026-10-01",
      "credits_consumed": 145,
      "breakdown": {
        "buyer": {
          "count": 50,
          "credits_consumed": 100
        },
        "signal": {
          "count": 15,
          "credits_consumed": 15
        },
        "email": {
          "count": 10,
          "credits_consumed": 20
        },
        "phone": {
          "count": 2,
          "credits_consumed": 10
        }
      }
    }
  ]
}
```

## Usage fields

| Field | Type | Description |
| - | - | - |
| `client_id` | string | Workspace ID. |
| `month` | string | Selected reporting month, `YYYY-MM`. |
| `available_months` | object | Inclusive supported reporting range: `from` and `to`. |
| `credit_costs` | object | Current configured credits per `buyer`, `signal`, `email`, and `phone` activity. |
| `monthly` | object | Selected month's authoritative total and activity breakdown. |
| `daily` | array | Daily totals and activity breakdowns in ascending date order. |

### Activity breakdown

Both `monthly.breakdown` and every daily `breakdown` contain `buyer`, `signal`, `email`, and `phone`. Each category has `count` and `credits_consumed`.

| Category | Meaning |
| - | - |
| `buyer` | Billable Buyer activity. |
| `signal` | Billable Signal activity. |
| `email` | Billable Email activity. |
| `phone` | Billable Phone activity. |

`count` measures the activity quantity. `credits_consumed` records credits actually charged for that category. `date` is the reporting-calendar date in `YYYY-MM-DD` format.

## Discover available history

Read `available_months.from` and `.to` before requesting historical months. Both are inclusive. Every successful response includes the range, even when requesting a historical month.

A supported month with no usage returns confirmed zero totals and the full daily date series. A month outside the range, or a future month, returns 400 rather than an invented zero-usage report.

Invalid formats include `2026-1`, `2026-13`, and `2026-10-01`.

## Daily coverage

* Historical months include every date in that calendar month, including weekends and zero-usage days.
* The current month includes dates from the first day through the current reporting date. Today's usage can increase as activity is processed.
* Future dates are excluded.
* Billing and Usage use the same authoritative calendar boundaries; the caller's local timezone does not redefine them.

## Pricing and historical consumption

`credit_costs` is the current configuration and matches [Billing](https://docs.1eye.ai/api-reference/billing.md). Historical `credits_consumed` reflects the prices charged when the activities occurred. Do not recalculate historical consumption by multiplying counts by today's costs.

For example, a historical month with 94 Buyers charged at 10 credits and 117 Signals charged at 1 credit consumed 1,057 credits, even if the current Buyer cost is now 2 credits.

## Unavailable historical categories

When an older category cannot be reliably reconstructed, its two values are `null` together:

```json theme={null}
{
  "count": null,
  "credits_consumed": null
}
```

This category object means unavailable reporting, not zero usage. A confirmed zero category uses numeric zeros. Authoritative monthly and daily credit totals remain available even when an older category breakdown is unavailable.

When every category is known, category credits sum to the containing total and daily totals sum to monthly usage. Credit purchases, grants, payment amounts, balances, and invoices belong to Billing and are not counted as usage activity.

## Errors

| Status | Error code | Description |
| - | - | - |
| 400 | `invalid_parameter` | A request field or query parameter is invalid. |
| 401 | `authentication_error` | The API key is missing, invalid, or revoked. |
| 403 | `permission_denied` | The key does not have permission for this operation. |
| 429 | `rate_limit_exceeded` | The workspace API rate limit was exceeded. |
| 500 | `internal_error` | An unexpected server error occurred. |
| 503 | `service_unavailable` | The service is temporarily unavailable. |

Errors use the standard [error envelope](https://docs.1eye.ai/api-reference/errors.md). Use `request_id` when contacting support.

### Unsupported month error

```json theme={null}
{
  "error": {
    "code": "invalid_parameter",
    "message": "Usage data is available from 2026-04 through 2026-10.",
    "param": "month",
    "request_id": "req_123456789012345678"
  }
}
```

The dates in an actual error describe the workspace's current available range.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.