> For the complete documentation index, see [llms.txt](https://developer.ballotpedia.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.ballotpedia.org/geographic-apis/usage.md).

# /usage

Check your current API usage against your plan's rate limit and quota. See also: [Rate limiting](/rate-limiting.md). Requires your API key, passed via the x-api-key header.

**Required parameters:** *none*

**Optional parameters:** *none*

<details>

<summary>Example call</summary>

```
https://api4.ballotpedia.org/data/usage
```

</details>

<details>

<summary>Example response</summary>

```json
{
    "success": true,
    "data": {
        "limit": 200000,
        "used": 2203,
        "remaining": 197797,
        "period": "DAY",
        "period_start": "2026-07-20",
        "period_end": "2026-07-20",
        "throttle": {
            "rate_limit": 5,
            "burst_limit": 100
        }
    },
    "message": "Usage limit retrieved."
}
```

</details>

## Details

**Definitions:**

* limit: The maximum number of requests allowed in the current quota period.
* used: Requests made so far in the current period.
* remaining: Requests remaining before you hit your quota.
* period: The quota period your plan resets on: DAY, WEEK, or MONTH.
* period\_start: Start date (UTC) of the current quota period.
* period\_end: End date (UTC) covered by this response — today's date.
* throttle.rate\_limit: Sustained requests per second your plan allows.
* throttle.burst\_limit: Maximum burst of concurrent requests allowed above the rate limit.

**Notes**

* Use of this API does count against your usage limits.
* Used/remaining counts reset every day at midnight UTC. If you have a specialized weekly or monthly quota, this may differ.
* AWS quota systems are designed to handle large-scale operations, and as a result, there can be some latency in updating and propagating quota information across their systems. This delay can affect the accuracy of quota monitoring tools and functions. Delays of up to a half hour are not uncommon.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.ballotpedia.org/geographic-apis/usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.