Developer API

Programmatic access to docket search, retrieval, documents, and AI-powered analysis.

Authentication

Docket Alarm uses token-based authentication. First call the login/ endpoint with your account username and password to obtain a login token. The token is valid for 90 minutes; include it as a login_token parameter on every other request (a query-string parameter on GET requests, or a form field on POST requests). Reuse a single token across many calls rather than logging in for each one.

Base URL https://www.docketalarm.com/api/v1/
POST /api/v1/login/

Parameters

Parameter Type Description
usernamerequired string Your Docket Alarm account username (usually your email address).
passwordrequired string Your Docket Alarm account password.

Example Request

# Exchange your credentials for a 90-minute login token POST https://www.docketalarm.com/api/v1/login/ username=you@example.com&password=••••••

Example Response

{ "success": true, "login_token": "a1b2c3d4e5f67890abcdef1234567890" }
Tip: A login token stays valid for 90 minutes, so reuse it across many requests rather than calling login/ every time, and request a fresh one once it expires. Never embed your password in client-side code. See API Conventions below for response formats and shared parameters.

API Conventions

A handful of conventions apply to every endpoint. Knowing them up front makes the rest of this reference easier to work with.

Requests

All calls are made over HTTPS to the base URL below. On GET requests, pass parameters as query-string values; on POST requests, send them as form fields with the header Content-Type: application/x-www-form-urlencoded.

Base URL https://www.docketalarm.com/api/v1/

Responses

Most endpoints return HTTP 200 with a JSON body. Every JSON response includes a boolean success field; when a request fails, success is false and an error field explains what went wrong. The exception is document retrieval, which returns the binary PDF on success and a JSON error only on failure.

Dates

Dates are returned in mm/dd/yyyy format, and any dates you submit should use the same format.

The client_matter field

Most data endpoints accept an optional client_matter field (up to 50 characters) that you can use to tag a call for your own billing or matter tracking. Whatever you pass is recorded in your account's usage history.

Versioning

Minor version increases (for example, 1.0 to 1.1) are always backwards compatible. A major version change (such as 1.0 to 2.0) may introduce breaking changes and will use a new endpoint URL, so an existing integration keeps working against the version it was built for.

Testing

To avoid charges while you build, add a test parameter to any GET or POST request to use the test-bed, which returns sample data instead of live results. A free Docket Alarm account is enough to try the API in test mode.

Rate Limits

The API enforces rate limits to keep the service fast and reliable for everyone. As a best practice, keep your request rate within the per-minute limits below. If you go over, requests may be throttled, so slow down and retry.

Endpoint Best-practice limit Window
Search 60 requests per minute
Get Docket 200 requests per minute
Get Document 300 requests per minute

What Counts as a Call

A call is a single request to one of the API endpoints. Your usage is measured in calls, so it helps to know what counts as one.

Endpoint What counts as one call
search/ One call per request against Docket Alarm's own database.
getdocket/ One call per docket you retrieve.
searchpacer/ One call per direct-to-court search. May also incur PACER fees of $0.10 per page of results.
getdocument/ One call per PDF you pull. Each document opened from a docket entry's link is its own call, and for federal cases it may carry PACER fees depending on the document.
login/ Authentication only. Not a call.

Paging: each page is its own call

Paging through results is not free. search/ returns at most 50 results per request, so each time you advance the offset to fetch the next batch, that is a separate call: ten pages of results is ten calls, not one. The same applies to searchpacer/, which returns 50 results per page and advances with the page parameter (each page may carry its own PACER fee).

Recommended: Use offset/limit to page through your results -- set offset to the number of results you've already seen and limit to how many you want next.

Example workflow

A typical sequence to find cases where Uber was a defendant, then pull dockets and filings:

  1. 1
    Not a call

    login/ once to get a login_token (good for 90 minutes).

  2. 2
    Call #1

    search/ with q=party:(name:uber type:defendant) is:docket, offset=0, limit=50 -- returns the first 50 results plus a total count.

  3. 3
    Call #2

    search/ again with offset=50 for results 51 to 100, a separate call purely because it is the next page. Repeat for each page.

  4. 4
    Call #3

    getdocket/ for a case from your results, passing its court and docket. cached=true returns Docket Alarm's stored copy; cached=false (or omitting it) pulls a fresh copy from the court and may trigger PACER fees. The response lists docket entries, each with a link to its PDF.

  5. 5
    Call #4

    getdocument/ to download a PDF using the link from a docket entry.

Search PACER

GET /api/v1/searchpacer/

Run a live search directly against PACER (federal courts) using PACER's own party and case-locator fields. This searches PACER in real time rather than the Docket Alarm index. A request that sends only login_token and client_matter returns the list of available parameter options. Results are paginated with page (see page_max in the response).

Reach for Search PACER when you need brand-new federal filings sooner than they reach Docket Alarm, which indexes newly filed federal cases within 24 hours of filing at most.

What to expect. Because Search PACER queries the federal courts live, it returns dockets only (not documents), reflects PACER exactly, and is slower than searching Docket Alarm (roughly 30 to 60 seconds per search). It also carries PACER's fees: $0.10 for the initial search, plus $0.10 per page of results accessed.

Parameters

Parameter Type Description
login_tokenrequired string Login token from login/.
client_matterrequired string Your client/matter code for billing and tracking (may be blank).
party_nameoptional string A company name, or an individual's last name.
first_name / last_nameoptional string First and last name when searching for an individual.
nature_of_suitoptional string[] One or more Nature of Suit (NOS) codes to filter by.
case_typeoptional string Restrict to a case type: Appellate, Bankruptcy, Civil, Criminal, or Multi-District Litigation.
date_filed_start / date_filed_endoptional date Filter to cases filed within a date range (YYYY-MM-DD).
pageoptional integer Page number (1-based) for paginating results.

Example Request

GET https://www.docketalarm.com/api/v1/searchpacer/?login_token=YOUR_TOKEN&client_matter=&party_name=Apple+Inc.&case_type=Civil

Example Response

{ "success": true, "page_max": 3, "search_results": [ { "title": "Apple Inc. v. Samsung Electronics Co. Ltd.", "court": "California Northern District Court", "docket": "5:11-cv-01846", "date_filed": "2011-04-15", "nature_of_suit": "830 Patent" } ] }

Return Values

A successful response contains the following top-level fields.

Field Type Description
success boolean true when the request succeeded. On failure it is false and an error field describes the problem.
page_max integer Up to 50 results are returned per search. When more than 50 cases match, this is the number of pages of data available; retrieve the rest with the page parameter.
search_results array The matching federal cases for this page. See search_results item below.

search_results item

Field Type Description
title string Case title.
court string PACER court the case is in.
docket string Docket number / case identifier.
date_filed string Date the case was filed.
link string URL to the docket on Docket Alarm.
nature_of_suitoptional string Nature of Suit (NOS) code. Bankruptcy cases do not have one.
date_terminatedoptional string Date the case was terminated, if it has closed.
party_nameoptional string Full party name. Returned when you searched by party_name.
party_roleoptional string The party's role in the case, for example Plaintiff or Defendant.

Discovering valid options

Send a request with only login_token and client_matter (no search fields) to retrieve the values this endpoint accepts. The response is a set of reference lists you can use to build a valid search.

Example Request

GET https://www.docketalarm.com/api/v1/searchpacer/?login_token=YOUR_TOKEN&client_matter=

Example Response

{ "success": true, "courts": ["California Northern District Court", "..."], "court_regions": ["..."], "nature_of_suits": ["830 Patent", "..."], "case_types": ["Appellate", "Bankruptcy", "Civil", "Criminal", "Multi-District Litigation"] }
Field Description
courts The PACER courts this endpoint can search.
court_regions Valid values for the court_region parameter.
nature_of_suits Valid Nature of Suit (NOS) codes for the nature_of_suit parameter.
case_types Valid values for the case_type parameter.

Get Docket

GET /api/v1/getdocket/

Retrieve a full case: normalized case info, the complete docket_report (every entry, with links to any documents), and the parties and their counsel. Results are normalized across all supported jurisdictions.

Important note on the cached parameter and costs: By default Docket Alarm pulls the docket live from the court, which can incur PACER and per-page charges. Set cached=true to return Docket Alarm's already-stored copy and avoid those charges. We recommend always setting cached=true unless you specifically need the very latest filings, since leaving it false triggers a live pull and can cost money on every call.

Parameters

Parameter Type Description
login_tokenrequired string Login token from login/.
client_matterrequired string Your client/matter code for billing and tracking (may be blank).
courtrequired string Court name, exactly as Docket Alarm names it, e.g. U.S. District Court, Northern District of California.
docketrequired string Docket number / case identifier, e.g. 5:11-cv-01846.
cachedoptional boolean If true, return the cached docket instead of pulling live from the court. Recommended. Default behavior pulls live and may incur costs.
normalizeoptional boolean If true, include normalized party, attorney, firm, and judge names.
use_last_filing_dateoptional boolean Skip the live pull if there has been no new activity since the last filing date, reducing PACER fees.

Example Request

# Recommended: request the cached copy to avoid live-pull charges GET https://www.docketalarm.com/api/v1/getdocket/?login_token=YOUR_TOKEN&client_matter=&court=U.S.+District+Court,+Northern+District+of+California&docket=5:11-cv-01846&cached=true

Example Response

{ "success": true, "info": { "title": "Apple Inc. v. Samsung Electronics Co. Ltd. et al", "date_filed": "2011-04-15", "judges": ["Lucy H. Koh"], "nature_of_suit": "830 Patent", "date_cached": "2024-11-14" }, "docket_report": [ { "date": "2011-04-15", "number": "1", "contents": "COMPLAINT against Samsung Electronics Co. Ltd.", "link": "https://www.docketalarm.com/cases/.../docs/1.pdf" } ], "parties": [ { "name": "Apple Inc.", "type": "Plaintiff" } ] }

Return Values

A successful response contains the following top-level fields.

Field Type Description
success boolean true when the request succeeded. On failure it is false and an error field describes the problem.
info object Normalized case information (title, judges, dates, and more). See info object below.
docket_report array Every docket entry for the case, in order. See docket_report entry below.
parties array The parties to the case and their counsel. See parties entry below.
related array Related cases, when available (each with court, docket, title, and link).
claims array Case claims, when available (type, description, code, disposition, date).

info object

Field Type Description
title string Case caption / title.
date_filed string Date the case was filed.
judges string[] Presiding judge(s). judges_normalized holds normalized names when normalize is requested.
nature_of_suit string Nature of Suit (NOS) classification.
type / status / cause string Case type, current status, and the cause of action.
date_terminated string Date the case was terminated, if closed.
patents string[] Patent numbers at issue (intellectual-property cases).
date_cached / datetime_cached string When Docket Alarm last pulled this docket from the court.
Note: Bankruptcy cases include additional fields such as chapter, date_341_meeting, and date_discharged.

docket_report entry

Field Type Description
date string Filing date of the entry.
number string Document / filing number, when the entry has one.
contents string The docket entry text (may contain HTML).
link / link_viewer string Link to the document PDF and to the Docket Alarm document viewer, when a document is available.
exhibits array Attached exhibits, each with its own document links.
analyze object Motion / order analysis when available, including the document type, outcome (e.g. granted or denied), and timing.

parties entry

Field Type Description
name string Party name. name_normalized holds the normalized form when requested.
type string Party role, e.g. Plaintiff or Defendant.
counsel array Attorneys for the party, each with name, firm, email, phone, and flags for lead counsel and prose (self-represented).

Get Document

GET /cases/{court}/{docket}/docs/{document_number}.pdf

Download a document as a PDF. You don't normally build this URL by hand. Each entry in a docket report's docket_report includes a link (and link_viewer) that points at the correct document URL. On success the response body is the binary PDF; on error it is JSON with success: false.

Important note on the cached parameter and costs: Including cached in the request at all -- with any value, including cached=false -- restricts the request to Docket Alarm's already-stored copy and avoids a paid live retrieval from the court. If the document is not yet cached, you get HTTP 412 instead of a charge. To force a live retrieval from the court, omit the cached parameter entirely rather than setting it to false.

Parameters

Parameter Type Description
login_tokenrequired string Login token from login/.
client_matteroptional string Your client/matter code for billing and tracking.
cachedoptional boolean If present -- any value, including false -- only return the document if it is already cached (returns 412 if not). Omit this parameter entirely to allow a live retrieval.

Example Request

GET https://www.docketalarm.com/cases/California-Northern-District-Court/5:11-cv-01846/docs/1.pdf?login_token=YOUR_TOKEN&cached=true

Response

# On success: binary PDF (Content-Type: application/pdf) # On error: JSON, e.g. { "success": false, "error": "Document is not in the cache." }

Status Codes

Code Meaning
200Success. The response body is the PDF, not JSON.
302Redirect. Follow the Location header (the document's link format changed).
401A problem with logging in. Check your login_token.
403The document is sealed or otherwise unavailable.
404The document could not be found in the docket. Double-check the link.
412You set cached, but the document is not in Docket Alarm's cache.
500Likely an API bug. Contact support.
502The servers are under heavy load. Retry later.

Ask a Docket

GET /api/v1/VIDA/ask_docket/

Ask a natural-language question about a case and get an AI-generated answer grounded in the case record. The model can read the docket entries, the underlying documents, or both, and returns an answer formatted however you describe in output_format. Optionally include the supporting source data used to answer.

Parameters

Parameter Type Description
login_tokenrequired string Login token from login/.
client_matterrequired string Your client/matter code for billing and tracking (may be blank).
courtrequired string Court name for the case.
docketrequired string Docket number for the case.
questionrequired string The natural-language question to ask about the case.
targetrequired string What the AI should read: docket, documents, or both.
output_formatrequired string A natural-language description of how the answer should be formatted.
cachedoptional boolean Use cached case data. Default: true.
show_relevantoptional boolean If true, include the docket/document data the answer was based on. Default: false.
openai_model / claude_modeloptional string Override the model used.
openai_key / anthropic_keyrequired string Your own API key to run the request against, sent via the X-OpenAI-Key / X-Anthropic-Key header. At least one of the two is required.

Example Request

GET https://www.docketalarm.com/api/v1/VIDA/ask_docket/?login_token=YOUR_TOKEN&client_matter=&court=S.D.N.Y.&docket=1:23-cv-01234&question=What+is+the+current+status+and+next+hearing%3F&target=both&output_format=a+short+paragraph

Example Response

{ "success": true, "question": "What is the current status and next hearing?", "price": 0.12, "from_documents": { "claude_answer": "The case is in discovery; a status conference is set for January 15, 2025 (Dkt. 47)." } }

Return Values

Field Type Description
success boolean true when the request succeeded; otherwise false with an error.
question string The question that was asked, echoed back.
price number The cost of the AI call.
date_cached string When the underlying case data was last cached.
from_dockets / from_documents object The answer. from_dockets is present when target includes the docket, from_documents when it includes documents. Each contains openai_answer and/or claude_answer, plus the supporting source data when show_relevant is true.

Track a Case

POST /api/v1/track/

Start or stop tracking a case (or a saved search). When tracking is enabled, Docket Alarm checks the case at the frequency you choose and notifies you, by email and/or push notification, whenever it changes. Send a GET to the same endpoint to list the cases you are currently tracking.

Request Body (form-encoded)

Field Type Description
login_tokenrequired string Login token from login/.
courtoptional string Court name for the case to track. Required unless q is set.
docketoptional string Docket number for the case to track. Required unless q is set.
enablerequired boolean true to start tracking, false to stop.
client_matteroptional string Your client/matter code for billing and tracking (may be blank). Required when enable=true.
frequencyoptional string How often to check the case: realtime, continuous, 40x, twice_daily, daily, weekly, or monthly. Required when enable=true.
qoptional string A search query. Use instead of court/docket to track a saved search rather than a single case.
testoptional boolean Send a test push notification with fake data to your configured api_push_url, without creating or modifying a tracker.
test_trackoptional boolean Synchronously send a real test push for an existing case or search tracker.
Notifications: Tracked-case updates can be delivered by email or as push notifications (webhooks) to a server endpoint you configure on your account. See Receiving Push Notifications in the official documentation for the delivery setup.

Example Request

POST https://www.docketalarm.com/api/v1/track/ Content-Type: application/x-www-form-urlencoded login_token=YOUR_TOKEN&court=S.D.N.Y.&docket=1:23-cv-01234&enable=true&client_matter=&frequency=daily

Example Response

{ "success": true }

Listing tracked cases

Send a GET to the same endpoint to list the cases and searches you are currently tracking.

Parameter Type Description
login_tokenrequired string Login token from login/.
offsetoptional integer Starting position in your tracker list. Default: 0.
limitoptional integer Maximum trackers to return. Default: 20. Max: 50.

Example Request

GET https://www.docketalarm.com/api/v1/track/?login_token=YOUR_TOKEN&limit=25

Example Response

{ "success": true, "dockets": [ { "court": "S.D.N.Y.", "docket": "1:23-cv-01234", "title": "Acme Corp. v. Widget Inc.", "link": "https://www.docketalarm.com/cases/...", "enabled": true, "frequency": "daily", "client_matter": "", "datetime_updated": "2026-01-15T09:30:00Z" } ] }

Each tracker returns its court, docket, title, link, enabled state, frequency, client_matter, and datetime_updated (ISO 8601).

Push Notifications

POST Docket Alarm → your callback URL

Instead of polling, you can have Docket Alarm push updates to you. When a tracked event is detected, Docket Alarm sends an HTTP POST request to a callback URL you configure. This is the delivery mechanism behind Track a Case.

Configuring your endpoint

Set your callback URL in one of two ways: email Docket Alarm to have an endpoint configured for your account, or set the api_push_url parameter when you create or modify a sub-account. The URL may include HTTP basic-auth credentials, for example https://user:password@example.com/webhook.

What triggers a notification

push_type Trigger
docketA new docket entry is detected on a case you track.
search_resultsA new result matches a saved search (new lawsuits, or new documents across many cases).
new_caseA new PACER case matches a tracked nature-of-suit search.

Payload

Docket Alarm POSTs a JSON body whose fields depend on push_type. A new docket-item notification looks like:

{ "push_type": "docket", "client_matter": "...", "court": "S.D.N.Y.", "docket": "1:23-cv-01234", "info": { /* case information */ }, "docket_report": [ /* new entries only */ ], "parties": [ /* case parties */ ] }

Every payload includes push_type and client_matter. A search_results push also carries q, link, title, and search_results; a new_case push carries party_name, nature_of_suit, and search_results.

Responding and retries

Your endpoint must return HTTP 200. If Docket Alarm receives a non-200 response, it retries up to 10 times with exponentially increasing delays, from a minimum of 10 minutes up to a maximum of 4 hours.

Testing and debugging

To simulate a push without changing a tracker, add test=true to a POST to track/ -- Docket Alarm ignores every other parameter and sends a notification with fixed, fake data, so you can check your endpoint is wired up correctly. To test against a real existing tracker instead, use test_track=true along with the court/docket or q identifying it -- Docket Alarm synchronously sends a notification with that tracker's actual current results, without editing the tracker. The track/ GET response also includes an _api_push_debug_info object (response_code, request_url, request_payload, will_retry, error_message) to help troubleshoot delivery. This debug field is not covered by the versioning policy.