# Usage

Credit balance and consumption, broken down by day, endpoint, and key. Free to call.

## Endpoints

| Method | Path | Scope | Credits | Description |
|---|---|---|---|---|
| GET | `/v1/usage` | `usage:read` | 0 | Consumption report |

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `start_date` | date | no | Inclusive; defaults to the start of the current billing period |
| `end_date` | date | no | Inclusive; defaults to today |
| `group_by` | enum[] | no | Any of `date`, `endpoint`, `api_key`. Omit for totals only |

## Response

```json
{
  "object": "usage",
  "period": {
    "start_date": "2026-08-01",
    "end_date": "2026-08-10"
  },
  "credits": {
    "granted": 10000,
    "consumed": 3140,
    "remaining": 6860,
    "renews_at": "2026-09-01T00:00:00Z"
  },
  "breakdown": [
    {
      "date": "2026-08-09",
      "endpoint": "searches",
      "api_key": "key_ak91ndu3fs",
      "requests": 412,
      "credits": 2060
    },
    {
      "date": "2026-08-09",
      "endpoint": "chats.messages",
      "api_key": "key_ak91ndu3fs",
      "requests": 540,
      "credits": 1080
    }
  ]
}
```

`granted` includes plan credits plus any top-ups. Unused credits do not roll over.

## Retrieve usage by key

```bash
curl -G https://api.scispace.com/v1/usage \
  -H "Authorization: Bearer $SCISPACE_API_KEY" \
  --data-urlencode "start_date=2026-08-01" \
  --data-urlencode "group_by[]=api_key" \
  --data-urlencode "group_by[]=endpoint"
```

## Reconciliation

`X-Credits-Cost` on each response is authoritative in real time; `/v1/usage` is the daily record and
may lag live traffic by up to 5 minutes. Reconcile daily, not per request.

## Errors

| Status | `code` | When |
|---|---|---|
| 400 | `parameter_invalid` | `start_date` after `end_date`, or a window over 365 days |
| 403 | `scope_missing` | key lacks `usage:read` |

## Related

credit · pricing-and-credits · cost-control · api-keys