# Get the workspace's plan usage

`GET https://api.tryscouty.com/v1/usage`

Reports this workspace's plan usage for the current period: usage as one whole percent (usagePct), outreach credits used against the plan's, Creators Club invites used against the plan's, active campaigns against the plan's, how many Creators Club applicants are held until the plan starts, how many creator emails searches found, and when the counts reset. Usage is null for a workspace with no workspace plan, which includes every campaign on its own plan. Amounts are not part of this answer.

- Scope: `plan:read`
- Kind: read
- MCP tool: `scouty_get_usage`

## Authorization

Send `Authorization: Bearer $SCOUTY_TOKEN`. The token needs the `plan:read` scope.

## Request

### cURL

```bash
curl -s https://api.tryscouty.com/v1/usage \
  -H "Authorization: Bearer $SCOUTY_TOKEN"
```

### JavaScript

```js
const response = await fetch("https://api.tryscouty.com/v1/usage", {
  headers: {
    Authorization: `Bearer ${process.env.SCOUTY_TOKEN}`,
  },
});
console.log(await response.json());
```

### Python

```python
import os

import requests

token = os.environ["SCOUTY_TOKEN"]
response = requests.get(
    "https://api.tryscouty.com/v1/usage",
    headers={"Authorization": f"Bearer {token}"},
)
print(response.json())
```

## Responses

### 200 OK

```json
{
  "usage": {
    "tier": "<plan tier>",
    "trial": false,
    "trialing": false,
    "periodEnd": "2026-10-15T00:00:00.000Z",
    "searchUsedPct": "<integer, 0 to 100>",
    "outreachUsed": "<integer>",
    "outreachAllowance": "<integer>",
    "recruitingUsed": "<integer>",
    "recruitingAllowance": "<integer>",
    "discoveryUsed": "<integer>",
    "usagePct": "<integer, 0 to 100>",
    "invitesUsed": "<integer>",
    "invitesAllowance": "<integer>",
    "activeCampaignsUsed": "<integer>",
    "activeCampaignsAllowance": "<integer>",
    "applicationsWaiting": "<integer, or null when not on a trial>"
  }
}
```

### 401 Unauthorized

```json
{
  "error": {
    "code": "missing_token",
    "message": "This API needs an Authorization header carrying a bearer token."
  }
}
```

### 403 Forbidden

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "This token does not carry the plan:read scope. Ask the team for one that does."
  }
}
```

### 429 Too Many Requests

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please wait for the current minute to end."
  }
}
```

## Errors

| Status | `error.code` | Meaning |
|---|---|---|
| 401 Unauthorized | `missing_token`, `invalid_token`, `token_revoked`, `token_expired`, `token_orphaned` | No token, or one that is not recognized, revoked or expired. |
| 403 Forbidden | `insufficient_scope`, `wrong_principal` | The token does not carry the scope this capability needs. |
| 429 Too Many Requests | `rate_limited` | Too many requests this minute. Retry-After says how long is left. |

Full reference: https://docs.tryscouty.com/reference