API Usage API

Use this API to see your rate limits, how much of them you have used, and when they reset.

Overview

Every CourtListener API request counts against a limit. This API tells you where you stand against those limits right now. Use it to pace a long job instead of hitting a wall halfway through, to work out which limit produced an HTTP 429, or to confirm that a membership upgrade raised your access.

Your API usage page in the web interface shows the same daily counts and your main API limits. This API reports more: your live usage and remaining allowance in every scope, when each window frees up, and your membership.

Your Usage and Access

This API uses the same authentication as the rest of the CourtListener APIs, and it requires it. Anonymous requests get an HTTP 401 Unauthorized. It does not support filtering, pagination, ordering, or field selection, and it takes no query parameters. Anything you put in the query string is ignored.

Usage

Send an HTTP GET request with no parameters:

curl -X GET \
  --header 'Authorization: Token <your-token-here>' \
  "https://www.courtlistener.com/api/rest/v4/api-usage/"

The response:

{
  "current_usage": [
    {
      "scope": "user",
      "rate": "125/day",
      "used": 63,
      "limit": 125,
      "remaining": 62,
      "window_seconds": 86400,
      "reset_at": "2026-08-07T15:03:52.762401+00:00",
      "blocked": false
    },
    {
      "scope": "user",
      "rate": "5/min",
      "used": 2,
      "limit": 5,
      "remaining": 3,
      "window_seconds": 60,
      "reset_at": "2026-08-07T14:32:40.481932+00:00",
      "blocked": false
    },
    {
      "scope": "user",
      "rate": "50/hour",
      "used": 18,
      "limit": 50,
      "remaining": 32,
      "window_seconds": 3600,
      "reset_at": "2026-08-07T14:41:26.094117+00:00",
      "blocked": false
    },
    {
      "scope": "api_usage",
      "rate": "10/min",
      "used": 3,
      "limit": 10,
      "remaining": 7,
      "window_seconds": 60,
      "reset_at": "2026-08-07T14:32:20.640518+00:00",
      "blocked": false
    },
    {
      "scope": "citations",
      "rate": "60/min",
      "used": 12,
      "limit": 60,
      "remaining": 48,
      "window_seconds": 60,
      "reset_at": "2026-08-07T14:32:55.203866+00:00",
      "blocked": false
    },
    {
      "scope": "api_usage",
      "rate": "120/hour",
      "used": 9,
      "limit": 120,
      "remaining": 111,
      "window_seconds": 3600,
      "reset_at": "2026-08-07T14:47:33.118274+00:00",
      "blocked": false
    },
    {
      "scope": "fetch",
      "rate": "30/min",
      "used": 0,
      "limit": 30,
      "remaining": 30,
      "window_seconds": 60,
      "reset_at": null,
      "blocked": false
    }
  ],
  "historical_usage": {
    "2026-07-25": 8,
    "2026-07-26": 3,
    "2026-07-30": 14,
    "2026-08-03": 27,
    "2026-08-04": 9,
    "2026-08-06": 22,
    "2026-08-07": 41,
    "total": 124
  },
  "membership": null
}

That is a user on our default limits, with no membership. Reading the top row: they have used 63 of their 125 daily requests, 62 are left, and the oldest request of the day drops out of the window at 15:03:52 UTC. The daily limit is listed first because it is the constraint closest to biting, at 50% consumed, against 40% of the per-minute limit and 36% of the per-hour limit.

To learn more about this API, make an HTTP OPTIONS request:

curl -X OPTIONS \
  --header 'Authorization: Token <your-token-here>' \
  "https://www.courtlistener.com/api/rest/v4/api-usage/"

This endpoint has no serializer and no filters, so the OPTIONS response describes the endpoint but does not list the response fields. Those are documented below. An OPTIONS request counts against this endpoint's own throttle, the same as a GET.

Field Definitions

The response has three top-level keys: current_usage, historical_usage, and membership.

Current Usage

current_usage is a list with one row for each scope and rate combination, not one row per scope.

You have more than one limit at a time. A user on our defaults is capped at 5 requests per minute, 50 per hour, and 125 per day, and all three apply at once. Each one gets its own row, all with "scope": "user". The most restrictive one, given your recent traffic, is what decides whether your next request is accepted.

Rows are sorted by how much of each window you have used (used divided by limit), fullest first, so the first row is the constraint closest to biting. If you read only one row, read that one.

The fields in each row are:

scope — The family of requests a limit covers. It can have one of four values:
- user — The main API quota. It covers ordinary REST requests to both v3 and v4, and citation lookups count against it too. Our default is 5 per minute, 50 per hour, and 125 per day. When a promotional doubling is running on your account, it applies to this scope only, and these numbers reflect it.
- citations — The Citation Lookup API. Our default is 60 per minute. Citation lookups are checked against this scope and against your user scope, so each lookup request also consumes one request from your main API quota.
- fetch — The RECAP Fetch API, which buys documents from PACER on your behalf. Our default is 30 per minute. It runs on its own limit rather than your main quota, so buying documents does not eat into your other API access.
- api_usage — This endpoint's own limit, reported for completeness. Our default is 10 per minute and 120 per hour.
CourtListener has other throttles, for anonymous traffic among others, but they are not reported here.
rate — The limit in the form <count>/<period>, such as 125/day. A rate of 0/min means your account is blocked from that scope.
used — How much of the window you have consumed. For most scopes this is a count of requests. On the citations scope it is a count of citations.
limit — The count from rate. This is the most you can consume before the window closes on you.
remaining — limit minus used, never less than zero. When this is 0, your next request in that scope will be refused.
window_seconds — How long the rolling window is: 60 for a per-minute rate, 3600 for per-hour, 86400 for per-day. Windows roll continuously, so allowed access refills as earlier requests fall out the back of the window. There is no concept of a clock hour or a calendar day here.
reset_at — An ISO-8601 timestamp in UTC, with microseconds, for when this window next frees up capacity. It is null in two different situations. See Reset Times.
blocked — true when limit is 0, meaning your account has been blocked from that scope. Otherwise false.

Note

The Citation Lookup API is throttled by how much work it has to do, so one request carrying 40 citations consumes 40. A citations row reading "used": 12 against a 60/min rate means you have 48 citations left this minute, however many requests you spend them in.

These are the numbers we actually enforce. If a membership or our staff has raised your limits, these rows show your raised limits, not our defaults. An override replaces the whole default list for a scope, so if you have a single override on the main API scope you will see one user row rather than three.

Reset Times

reset_at tells you when the window next frees up capacity, which is not always the same as when you can make your next request.

When remaining is 0, reset_at is the time you can go again. For the user, fetch, and api_usage scopes, it is the moment the Retry-After header on your 429 counts down to. The Citation Lookup API reports the same instant as a wait_until timestamp in its error body instead, and sends no Retry-After.
When remaining is above 0, you can make a request right now. reset_at is only the moment your oldest in-window request expires and your capacity grows by one.

reset_at is null in two situations that mean opposite things:

The window is empty. You have used nothing in that scope, so there is nothing to expire, and blocked is false. Go ahead and make requests.
Your account is blocked, with a limit of 0 and blocked set to true. No amount of waiting will admit a request, so there is no reset time to report.

You can't tell those apart from reset_at alone, so check blocked.

Historical Usage

historical_usage is an object of daily request counts covering the last 15 calendar days, today included. Keys are ISO dates, values are integers, and the counts combine your v3 and v4 requests.

Days with no usage are left out, so a missing date means zero rather than missing data. A total key is always present, even when it is 0; it is the sum over the whole window and always sits last. These are calendar days, while current_usage uses rolling windows, so the two sets of numbers describe different things and will not add up to each other.

Requests to this endpoint are not counted here, and neither are requests that were refused with a 429. If your daily counts fall off a cliff, that is a sign your requests are being throttled rather than a sign you stopped sending them.

Membership

membership describes your Free Law Project membership, because membership is what raises your limits.

level — The human-friendly name of your membership, such as CL Membership - Tier 2 or EDU Membership. If your membership level isn't one we recognize, this reads Unknown.
is_active — Whether the membership is current.

This key is null when you have no membership on file. If your membership lapsed or a payment failed, you get an object with "is_active": false instead of a null. An expired membership does not raise your limits.

You may be eligible for a Free Law Project membership to expand your API access. Commercial agreements are also available.

Join Free Law Project Become a Partner

Limitations & Throttles

This API has its own throttle, on the api_usage scope: 10 requests per minute and 120 per hour by default. We kept it separate from every limit it reports, so checking your usage never consumes the quota you are checking. Calls to this endpoint do not touch your user scope and do not appear in historical_usage.

That separation also means this endpoint keeps answering after your other requests have started failing. If you have exhausted your main quota, or your account has been blocked outright, you can still read your usage and your reset times, which is when you need them most.

The api_usage scope cannot be raised by a membership or a staff override.

A few other limitations to be aware of include:

Authentication is required. Anonymous requests get an HTTP 401 Unauthorized.
This API has a list view only. There is no URL for a single item, and it accepts only GET, HEAD, and OPTIONS requests. Anything else returns an HTTP 405 Method Not Allowed.
There are no query parameters, no filters, no ordering parameter, and no pagination. The response is a flat object, not a paginated envelope. Unknown query parameters are ignored rather than rejected.

API Examples

Diagnosing a Throttled Request

When an ordinary API request is refused, you get an HTTP 429 with a Retry-After header and a body like this:

{
  "detail": "Request was throttled. Rate limit exceeded: 5/min. Expected available in 37 seconds."
}

That tells you one limit was hit, but not which others you are close to. Call this API to see the whole picture. The row whose remaining is 0 is the one that stopped you, and its reset_at is the moment the Retry-After header counts down to. Check the other rows too. Clearing a per-minute limit does you no good if you are also one request away from your daily one.

Confirming a Membership Upgrade

After joining or upgrading, call this API and check two things.

First, the membership object should be present and current:

{
  "level": "CL Membership - Tier 2",
  "is_active": true
}

Second, and more to the point, look at the limit on your user rows. Those are the numbers we actually enforce. If they are still 5, 50, and 125, your upgrade has not taken effect yet, whatever the membership object says.

Throttled by This API

If you poll this endpoint too hard, it throttles you like any other:

{
  "detail": "Request was throttled. Rate limit exceeded: 10/min. Expected available in 37 seconds."
}

The response carries a Retry-After header. There is no need to poll aggressively. The rolling windows move steadily, and a check before each batch of work is usually enough.

To learn how the limits themselves work, how rolling windows refill, and how to get more access, read the rate limit documentation. If your key looks throttled and you are not sure why, start with our FAQ on the subject.

Rate Limit Docs Throttling FAQ

API Usage