Free trademark search
Search our daily-refreshed copy of the USPTO register by name, with exact and fuzzy matching and filters for owner, class, and status. No key required.
Search now →Developer guide
USPTO TSDR API
TSDR — Trademark Status & Document Retrieval — is the USPTO's API for pulling the status and documents of a single trademark by its serial or registration number. Here's what the TSDR API does, how to authenticate, and the JSON it returns — plus the one thing it can't do: search.
Or start free — 200 API calls/month, no credit card.
Background
What is the USPTO TSDR API?
TSDR stands for Trademark Status & Document Retrieval. It is the USPTO's official service for retrieving everything on file for a known trademark application or registration: its current status, prosecution history, owner, and the underlying document images. The API lives at tsdrapi.uspto.gov/ts/cd/ and returns JSON, XML, or PDF. Since 2020 it requires a free USPTO API key. It is the machine-readable counterpart to the TSDR portal at tsdr.uspto.gov.
Reference
Endpoints, authentication & formats
Authenticate by sending your key in a USPTO-API-KEY header — get one from a MyUSPTO / USPTO Open Data Portal account. Every endpoint is keyed on a serial (sn) or registration (rn) number you already have.
| What you get | Path (under tsdrapi.uspto.gov/ts/cd/) |
|---|---|
| Status by serial number (JSON) | casestatus/sn{serialNumber}/info.json |
| Status by registration number (JSON) | casestatus/rn{registrationNumber}/info.json |
| Status as XML | casestatus/sn{serialNumber}/info.xml |
| Status as a PDF | casestatus/sn{serialNumber}/download.pdf |
| Status as HTML, or zipped XML + CSS | casestatus/sn{serialNumber}/content · …/content.zip |
| All documents (PDF) | casedocs/bundle.pdf?sn={serialNumber} |
| Document metadata (XML) | casedocs/bundle.xml?sn={serialNumber} |
| Documents as original images (ZIP) | casedocs/bundle.zip?rn={registrationNumber} |
| Full-size mark image | rawImage/{serialNumber} |
Fetch a mark's status as JSON in one request:
curl -H "USPTO-API-KEY: your_uspto_key" \ "https://tsdrapi.uspto.gov/ts/cd/casestatus/sn88888888/info.json"
Narrowing a document bundle
The casedocs endpoints take query parameters rather than a path number, so one request can cover several cases or a slice of a file history. bundle.pdf returns the documents, bundle.zip their original images, and bundle.xml metadata about the documents instead of the documents themselves.
| To get | Example (under tsdrapi.uspto.gov/ts/cd/casedocs/) |
|---|---|
| By registration or reference number | bundle.pdf?rn=3500030 · bundle.pdf?ref=Z1231384 |
| By international registration number | bundle.xml?ir=0835690 |
| Several cases in one file | bundle.pdf?sn=72131351,76515878 |
| One day's documents | bundle.pdf?sn=72131351&date=2003-11-30 |
| A date range | bundle.xml?sn=75008897&fromDate=2006-01-01&toDate=2006-12-31 |
| One document type (e.g. specimens) | bundle.pdf?sn=72131351,76515878&type=SPE |
| One category (e.g. registration certificate) | bundle.pdf?rn=3500038&category=RC |
| Sorted oldest to newest | bundle.xml?ir=0835690&sort=date:A |
Rate limits
USPTO publishes these ceilings per API key per minute. Exceeding them returns 429.
| Requests | Standard | 10 p.m.–5 a.m. ET |
|---|---|---|
| All requests | 60 / min | 120 / min |
| PDF and ZIP downloads | 4 / min | 12 / min |
| Multi-case PDF and ZIP | 4 / min | 12 / min |
Limits, endpoint paths and access requirements are USPTO's and may change; these are the figures published in USPTO's TSDR API Key Manager user guide (September 2020), which also states they are subject to change with system availability and usage.
Checking whether a case has changed
A separate service, outside the /ts/cd/ paths, reports when a case was last modified — so a docketing tool can poll cheaply and pull the full record only when something moved.
curl -H "USPTO-API-KEY: your_uspto_key" \ "https://tsdrapi.uspto.gov/last-update/info.json?sn=78787878"
The response carries a lastModifiedDate for the case and separately for its status, prosecution and document data.
The catch
TSDR is lookup, not search
Every TSDR endpoint requires a serial or registration number up front. There is no way to search by mark text, owner, goods/services, class, or status. TSDR answers “what is the status of application 88888888?” It cannot answer “which live marks contain ACME in class 9?” — the question you actually have when clearing a name or monitoring a brand. For that you need a trademark search API.
The alternative
Searching US trademarks without a serial number
Goalie IP maintains its own daily-refreshed copy of the USPTO register and exposes it three ways — a free search UI, a JSON search API, and an MCP server for AI agents. All three do what TSDR can't: find the marks before you have their numbers, then let you pull full detail.
Trademark Search API
The programmatic counterpart to TSDR's lookup: POST a query and search 14M+ records by mark literal, owner, class, status, and date — clean JSON, pagination built in.
See the API →Trademark MCP server
The same search exposed to AI agents over the Model Context Protocol — point Claude, Cursor, or any MCP client at one URL. Included with every API plan.
See the MCP server →FAQ
USPTO TSDR API questions
What is the USPTO TSDR API?
TSDR (Trademark Status & Document Retrieval) is the USPTO's official API for retrieving the status and documents of a single trademark by its serial or registration number. Call it at https://tsdrapi.uspto.gov/ts/cd/ to get a mark's current status, prosecution history, and document images as JSON, XML, or PDF. It is a lookup service — you must already know the number.
Is the TSDR API free?
Yes. The TSDR API is free to use, but since 2020 it requires a free API key from the USPTO, obtained through a MyUSPTO / USPTO Open Data Portal account. The key is sent in a USPTO-API-KEY request header, and the USPTO enforces per-key rate limits.
How do I get a trademark's status by serial number from TSDR?
Send a GET request to https://tsdrapi.uspto.gov/ts/cd/casestatus/sn{serialNumber}/info.json with your key in the USPTO-API-KEY header. The JSON response includes the current status code and date, filing basis, owner, and prosecution history. Swap sn for rn to look up by registration number, or /info.xml for XML.
Can the TSDR API search trademarks by name?
No. TSDR only retrieves a record you already have the serial or registration number for — there is no way to search by mark text, owner, goods/services, or class. To find marks you don't have numbers for, you need a trademark search API. Goalie IP's Trademark Search API runs exact, contains, and fuzzy mark search plus owner/class/status/date filters over 14M+ USPTO records as JSON.
What is the difference between TSDR and a trademark search API?
TSDR is retrieval: it answers "what is the status of application 88888888?" A trademark search API is discovery: it answers "which live marks contain ACME in class 9?" TSDR needs the number up front; a search API searches the whole register by mark, owner, class, status, and date. Most workflows need both — search to find the marks, then retrieve full detail.
What does the TSDR casestatus info.json endpoint return?
GET https://tsdrapi.uspto.gov/ts/cd/casestatus/sn{serialNumber}/info.json returns the full status record for one trademark as JSON: its current status code and date, mark text, filing date and basis, owner name and address, attorney of record, international classes with goods and services text, and the prosecution history as a list of dated events. It is comprehensive but verbose, so most developers map it to a smaller shape before using it.
How is the TSDR casestatus URL built for a serial or registration number?
The path takes a two-letter prefix plus the number: sn for a serial number and rn for a registration number. So casestatus/sn88888888/info.json is a serial-number lookup and casestatus/rn5555555/info.json is a registration-number lookup, both under https://tsdrapi.uspto.gov/ts/cd/. There is no endpoint that accepts a mark name — TSDR is keyed on the number.
What is the difference between TSDR's info.json and info.xml?
They carry the same status data in different formats: swap the extension on the same path. info.json returns JSON and info.xml returns the ST.96 XML record. Document endpoints are separate and return PDF or ZIP rather than either format.
What does the TSDR casedocs endpoint return, and how do I filter it?
The casedocs endpoints return the documents in a case file rather than its status. GET https://tsdrapi.uspto.gov/ts/cd/casedocs/bundle.pdf?sn={serialNumber} returns every document as one PDF; bundle.zip returns them as their original images; and bundle.xml returns metadata about the documents instead of the documents themselves. The case can be identified by sn (serial), rn (registration), ref (reference) or ir (international registration) number, and several numbers can be comma-separated into a single file. Filters include date for one day, fromDate and toDate for a range, type for a document type such as SPE for specimens, category such as RC for the registration certificate, and sort=date:A for oldest first.
What are the USPTO TSDR API rate limits?
USPTO publishes these limits per API key per minute: 60 requests overall, and 4 for PDF or ZIP downloads, including multi-case downloads. Off-peak, from 10 p.m. to 5 a.m. Eastern every day, those rise to 120 requests and 12 downloads. Exceeding them returns HTTP 429. USPTO notes the limits are subject to change with system availability and usage.
Why does the USPTO TSDR API return 401, 403, or 429?
A 401 or 403 almost always means the USPTO-API-KEY header is missing, misspelled, or holds an inactive key. The header name must be exactly USPTO-API-KEY, not an Authorization header, and the roughly 40-character key comes from the API Key Manager at account.uspto.gov/api-manager using a USPTO.gov account. A 429 means you exceeded the per-key rate limit — 60 requests a minute, or 4 for PDF and ZIP downloads — so slow down and retry.
How do I check whether a trademark's prosecution history has changed?
TSDR has a last-update service, separate from the /ts/cd/ paths: GET https://tsdrapi.uspto.gov/last-update/info.json?sn={serialNumber} returns the last modified date for the case overall and for its status, prosecution and document data separately, so a docketing tool can poll cheaply and pull the full record only when something moved. Swap info.json for info.xml for the XML form.
Does the TSDR API return JSON?
Yes. Status endpoints return JSON (info.json) or XML (info.xml), and document endpoints return PDF or ZIP bundles. The JSON is comprehensive but verbose, so many developers map it to a smaller shape for application use.
Goalie IP is not affiliated with, or endorsed by, the United States Patent and Trademark Office (USPTO). TSDR is a USPTO service; endpoint paths and access requirements are set by the USPTO and may change. This page is general information, not legal advice, and covers US federal (USPTO) trademark data only.