# Usage

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/usage` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 0 credits per call |
| **Documentation** | https://www.piloterr.com/library/usage |

## Description

Retrieve real-time usage statistics and credit balance for your Piloterr account.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/usage' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Account usage overview

```json
{
  "period": {
    "end": "2026-04-25",
    "start": "2026-03-25"
  },
  "account": {
    "name": "Microsoft",
    "slug": "microsoft"
  },
  "api_key": {
    "alias": "my-api-key",
    "active": true,
    "quotas": {
      "daily": null,
      "total": null,
      "weekly": null,
      "monthly": null
    },
    "expires": null,
    "category": "development"
  },
  "credits": {
    "given": 0,
    "consumed": 0,
    "remaining": 0,
    "percent_used": 0
  },
  "remaining": 0,
  "rate_limit": {
    "per_minute": null,
    "per_second": null
  },
  "total_used": 15871,
  "renewal_date": "2026-04-25",
  "subscription": {
    "used": 15871,
    "total": 50,
    "remaining": 0,
    "percent_used": 31742
  }
}
```

## Documentation

## Overview
The Usage endpoint returns a complete snapshot of your Piloterr account's credit consumption, subscription status, rate limits, and API key metadata. Use it to monitor your usage programmatically and trigger alerts or top-ups before running out of credits.

## Quickstart
```
GET https://api.piloterr.com/v2/usage
```

## Parameters
This endpoint requires no query parameters. Authentication is performed via the `x-api-key` header.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `x-api-key` | string | yes | Your private Piloterr API key |

## Response fields
| Field | Type | Description |
|---|---|---|
| `remaining` | number | Total remaining credits on the account |
| `total_used` | number | Total credits consumed since account creation |
| `renewal_date` | string \| null | Date of the next subscription renewal (ISO 8601) |
| `period.start` | string | Start date of the current billing period |
| `period.end` | string | End date of the current billing period |
| `subscription.used` | number | Credits used from the subscription in the current period |
| `subscription.total` | number | Total subscription credits allocated per period |
| `subscription.remaining` | number | Remaining subscription credits in the current period |
| `subscription.percent_used` | number | Percentage of subscription credits consumed |
| `credits.given` | number | Bonus credits given to the account |
| `credits.consumed` | number | Bonus credits consumed |
| `credits.remaining` | number | Remaining bonus credits |
| `credits.percent_used` | number | Percentage of bonus credits consumed |
| `rate_limit.per_minute` | number \| null | Maximum API calls allowed per minute (null = unlimited) |
| `rate_limit.per_second` | number \| null | Maximum API calls allowed per second (null = unlimited) |
| `account.name` | string | Name of the Piloterr account |
| `account.slug` | string | Slug identifier for the account |
| `api_key.alias` | string | Human-readable alias of the API key used |
| `api_key.active` | boolean | Whether the API key is currently active |
| `api_key.category` | string | Category of the API key (e.g. `development`, `production`) |
| `api_key.expires` | string \| null | Expiry date of the API key, or null if it never expires |
| `api_key.quotas.total` | number \| null | Total request quota for the key (null = unlimited) |
| `api_key.quotas.daily` | number \| null | Daily request quota (null = unlimited) |
| `api_key.quotas.weekly` | number \| null | Weekly request quota (null = unlimited) |
| `api_key.quotas.monthly` | number \| null | Monthly request quota (null = unlimited) |

## Notes
- This endpoint requires a valid `x-api-key` header. Requests without a key will return `401 Unauthorized`.
- `percent_used` values may exceed 100 if top-ups or overage scenarios apply.
- `rate_limit` values are `null` for plans without rate limiting.

## Main use cases
- Monitor remaining credits in real time and trigger automated top-up workflows before exhausting your quota
- Build internal dashboards that display API consumption per team or project
- Set up alerting systems that notify your team when usage exceeds a defined threshold
- Validate API key status and expiry before running batch scraping jobs