Legal Alert APIs

Use these APIs to create, modify, list, and delete search and docket alerts in our system.

Once configured, alerts can notify you by email or with a webhook event sent to your server.

This page focuses on the alerts API itself. To learn more about alerts generally, read the alert documentation.

Search Alerts

Search alerts update you when there is new information in our search engine.

This system scales to support thousands or even millions of alerts, allowing organizations to stay updated about numerous topics. This is a powerful system when used with webhooks.

Search alerts have three required fields and one optional field:

name — A human-friendly name for the alert.
query — Search parameters you get from the front end, as a string.
rate — How frequently you want to receive email updates. Webhook events are always sent in real time. This field accepts the following values:
- rt — Real time
- dly — Daily
- wly — Weekly
- mly — Monthly
alert_type — This is a required field for RECAP Search Alerts, but it is ignored for other types. When used with RECAP Search alerts, this field specifies whether you want alerts for each new case matching the query or for both new cases and new filings.

For notifications on cases only, use the d type (short for "dockets"). For notifications on both cases and filings, use the r type (meaning all of RECAP). Read the search API documentation for more on this distinction.

Note

Search alerts do not support semantic search queries. If the query for an alert includes semantic=true, the semantic parameter will be ignored and the alert will behave as a keyword search alert.

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

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

Relative Dates Queries

Use relative dates in your queries to keep your searches and alerts dynamically up to date.

Learn More

Alert Throttles

Alerts can only be created according to your membership level or through a commercial agreement.

If a request exceeds your membership tier, the API responds with HTTP 403 Forbidden and a detail message explaining how to proceed. For example:

{
  "detail": "You've used all of the alerts included with your membership. To create this alert, upgrade your membership at https://donate.free.law/constituent/memberships/upgrade/xxx or disable a RECAP Alert."
}

Query Frequency Estimation

When you create an alert or change an existing alert's query, we estimate how many results that query would have produced over the last 100 days. This tells you how noisy an alert is likely to be, and it blocks queries that are too broad for our system to support.

On success, the estimate is returned under the estimated_hits key, as an integer:

{
  "resource_uri": "https://www.courtlistener.com/api/rest/v4/alerts/4839/",
  "id": 4839,
  "name": "Apple",
  "query": "q=\"Apple Inc\"",
  "rate": "rt",
  "alert_type": "o",
  "estimated_hits": 320
}

estimated_hits is only included when the query is set or changed (on creation, and on updates that modify the query). A PATCH that only changes a field like rate or name does not re-run the estimation and won't include the key.

Broad queries are rejected

If a query averages more than the maximum number of results per day we can support, the alert is not created and the API responds with HTTP 400 Bad Request. The response includes a human-readable detail message and the estimated_hits integer, so you can see how far over the limit the query is:

{
  "estimated_hits": 3400,
  "detail": "This query averages about 34 results per day, which is more than our system can support. Please narrow your query to have
fewer results per day."
}

To fix this, narrow the query (for example, add filters, a date range, or more specific terms) until it produces fewer than results per day.

The maximum allowed for an alert is 30 hits per day.

Invalid queries are rejected

A query that can't be parsed or validated is also rejected with HTTP 400 Bad Request. There are two cases.

The query fails basic validation (for example, a malformed parameter value). The error is returned under the query key:

{
  "query": "This query is invalid and can't be used for an alert."
}

The query is syntactically broken (for example, unbalanced parentheses or quotes, or a disallowed wildcard). The specific reason is returned under detail:

{
  "detail": "The query contains unbalanced parentheses."
}

Example Usage

Let's say we want to know about case law involving Apple Inc. On the front end, we search for "Apple Inc" (in quotes) and get query parameters like:

q=%22Apple%20Inc%22&type=o

We can create that as an alert with an HTTP POST request:

curl -X POST \
  --data 'name=Apple' \
  --data 'query=q=%22Apple%20Inc%22&type=o' \
  --data 'rate=rt' \
  --header 'Authorization: Token <your-token-here>' \
  "https://www.courtlistener.com/api/rest/v4/alerts/"

The response:

{
  "resource_uri": "https://www.courtlistener.com/api/rest/v4/alerts/4839/",
  "id": 4839,
  "date_created": "2025-05-02T15:29:32.048912-07:00",
  "date_modified": "2025-05-02T15:29:32.048929-07:00",
  "date_last_hit": null,
  "name": "Apple",
  "query": "q=\"Apple Inc\"",
  "rate": "rt",
  "alert_type": "o",
  "secret_key": "ybSBXwtDcMKI2SxPZDCEx02DSSUF7EEvx1CjOk4f",
    "estimated_hits": 287
}

Search alerts can be modified with HTTP PATCH requests. For example, to change the rate to dly:

curl -X PATCH \
  --data 'rate=dly' \
  --header 'Authorization: Token <your-token-here>' \
  "https://www.courtlistener.com/api/rest/v4/alerts/4839/"

Search Alerts can be deleted with HTTP DELETE requests:

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

To list your alerts, send an HTTP GET request with no filters:

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

Learn more about filtering, sorting, and serialization in the query refinement documentation.

Docket Alerts

/api/rest/v4/docket-alerts/

Docket alerts keep you updated about cases by sending notifications by email or webhook whenever there is new information in our system about a particular case. Use this API to create, modify, list, and delete docket alerts.

Docket alerts are always sent as soon as an update is available. See the help page on Docket Alerts to learn more about how we get updates.

Docket alerts have two fields you can set:

docket — Required: The docket you want to subscribe to or unsubscribe from.
alert_type — Whether to subscribe or unsubscribe from the docket.

This field is part of @recap.email's auto-subscribe feature. If you are not using @recap.email or have auto-subscribe disabled, you can ignore this field.

If you are using @recap.email and have auto-subscribe enabled in your profile, docket alerts will be automatically created for you as the system receives notification emails about cases. To permanently unsubscribe from a case for which you are receiving notifications from PACER, create an "Unsubscription" for the case.

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/docket-alerts/"

Learn more about filtering, sorting, and serialization in the query refinement documentation.

Example Usage

To create a Docket Alert, send a POST request with the docket ID you wish to subscribe to.

This example subscribes to docket number 1:

curl -X POST \
  --data 'docket=1' \
  --header 'Authorization: Token <your-token-here>' \
  "https://www.courtlistener.com/api/rest/v4/docket-alerts/"

The response:

{
  "id": 133013,
  "date_created": "2024-05-02T16:35:58.562617-07:00",
  "date_modified": "2024-05-02T16:35:58.562629-07:00",
  "date_last_hit": null,
  "secret_key": "Xv6sg4xkarzyWdzABi84AyjzV3CslJs9Ldippq3s",
  "alert_type": 1,
  "docket": 1
}

To unsubscribe from a docket, you can either delete the alert with an HTTP DELETE request:

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

Or, if you are using @recap.email and have auto-subscribe enabled, you can send an HTTP PATCH request to change it from a subscription (alert_type=1) to an unsubscription (alert_type=0):

curl -X PATCH \
  --data 'alert_type=0' \
  --header 'Authorization: Token <your-token-here>' \
  "https://www.courtlistener.com/api/rest/v4/docket-alerts/133013/"

To list your Docket Alerts, send an HTTP GET request with no filters:

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

Learn more about filtering, sorting, and serialization in the query refinement documentation.