# Current plan limits and monthly usage for the calling API account

`GET https://twitterscore.io/api/v1/limits`

Returns the limits attached to the API key's account and how much of the monthly quota has already been used. Usage is account-scoped: all named keys of one account share a single monthly counter, so this endpoint reports the same figures whichever of the account's keys is used. The response is never cached, and the call itself is counted against the monthly quota (the counter is incremented before the view runs, so `used` already includes this request). Unlike every other endpoint in this set, the success body has no `success` key: the top-level keys are `user_id` and `rates`. `rates` always has two entries: the first describes the monthly quota (total/used/remaining and when the 30-day counter window resets), the second describes the per-minute request rate (`total` requests per `period`).
**Nested fields**

- `rates[].period` (string): Window of the limit. First entry: always "month". Second entry: the unit parsed from the plan's rate string ("second", "minute", "hour" or "day", falling back to "minute" for an unknown suffix); in practice "minute".
- `rates[].total` (integer): Limit for the window: requests per month (first entry, ProfileAPIKeyModel.monthly, default 10000) or requests per rate window (second entry, parsed from ProfileAPIKeyModel.rate, default '1000/m').
- `rates[].used` (integer): Requests already counted in the current monthly window, including this call. Present only in the first (month) entry.
- `rates[].remaining` (integer): total − used for the monthly window (can go to 0; the enforcer blocks once used >= total). Present only in the first (month) entry.
- `rates[].reset_time_at` (string (ISO 8601 date-time, naive server-local time, milliseconds, no timezone suffix)): Moment when the current 30-day monthly counter expires and usage returns to 0. Present only in the first (month) entry.

## Parameters

_No query parameters besides the API key._

## Example request

```bash
curl -s "https://twitterscore.io/api/v1/limits" \
  -H "X-API-Key: $TWITTERSCORE_API_KEY" \
  -H "User-Agent: my-app/1.0 (contact@example.com)"
```

```python
import os, requests

r = requests.get(
    "https://twitterscore.io/api/v1/limits",
    params={},
    headers={"X-API-Key": os.environ["TWITTERSCORE_API_KEY"],
             "User-Agent": "my-app/1.0 (contact@example.com)"},
    timeout=15,
)
data = r.json()
if not data.get("success", True):      # errors arrive as success=false (see /developers/errors/)
    raise RuntimeError(data["message"])
print(data)
```

```javascript
const r = await fetch("https://twitterscore.io/api/v1/limits", {
  headers: { "X-API-Key": process.env.TWITTERSCORE_API_KEY,
             "User-Agent": "my-app/1.0 (contact@example.com)" },
});
const data = await r.json();
if (data.success === false) throw new Error(data.message);
console.log(data);
```

## Example response

```json
{
  "user_id": 48213,
  "rates": [
    {
      "period": "month",
      "total": 10000,
      "used": 1327,
      "remaining": 8673,
      "reset_time_at": "2026-10-28T09:14:52.318"
    },
    {
      "period": "minute",
      "total": 1000
    }
  ]
}
```

## Errors

Error codes this endpoint can return (see [Errors](/developers/errors/) for the body format): `api_key_missing`, `api_key_invalid`, `api_access_deactivated`, `api_key_revoked`, `method_not_allowed`, `rate_limited`, `quota_exceeded`, `server_error`.

---

Authentication: `X-API-Key` header (or `Authorization: Bearer`), see [Authentication](/developers/authentication/). Limits: per-minute rate and monthly quota by plan, see [Rate limits](/developers/rate-limits/). Machine-readable definition: [/openapi.json](/openapi.json).