ptab-cli

A command-line tool for querying the USPTO Patent Trial and Appeal Board (PTAB) API directly from your terminal. Search and retrieve IPR/PGR/CBM trial proceedings, decisions, documents, appeal decisions, and interference decisions.

Installation

pip install ptab-cli
# or
uv tool install ptab-cli
# or
pipx install ptab-cli

Quick Start

# 1. Save your API key
ptab configure

# 2. Search IPR proceedings
ptab proc search --q "petitionerPartyName:Apple" --type IPR

# 3. Look up a single trial
ptab proc get IPR2023-00001

# 4. List decisions for a trial
ptab decision list IPR2023-00001

API Key Setup

Priority order (highest first):

ptab configure          # Interactive setup (API key, timeout, proxy, CA bundle)
ptab configure --show   # Show current configuration

Timeout follows the same priority:

• --timeout N global option
• REQUEST_TIMEOUT environment variable
• ~/.ptab-cli.toml [http] timeout (default: 30s)

Proxy & TLS Configuration

If you are behind a corporate proxy or need a custom CA bundle, run ptab configure and fill in the proxy/CA fields, or edit ~/.ptab-cli.toml directly:

[proxy]
https = "http://proxy.example.com:8080"
http  = "http://proxy.example.com:8080"

[ssl]
ca_bundle = "/path/to/ca-bundle.crt"

• Omitting a key leaves requests to fall back to the standard environment variables (HTTPS_PROXY, HTTP_PROXY, REQUESTS_CA_BUNDLE).
• Set ca_bundle to the path of a PEM file to verify against a private CA.
• Proxy and CA settings apply to every command automatically once saved.

Commands

proc — Trial Proceedings (IPR/PGR/CBM)

ptab proc search [--q Q] [--type IPR|PGR|CBM] [--from DATE] [--to DATE] [--limit N] [--sort FIELD]
ptab proc get TRIAL_NUMBER
ptab proc download [--q Q] [--type IPR|PGR|CBM] [--from DATE] [--to DATE] --out FILE.json

decision — Trial Decisions

ptab decision search [--q Q] [--type TYPE] [--petitioner NAME] [--patent NUMBER] [--from DATE] [--to DATE]
ptab decision get DOC_ID
ptab decision list TRIAL_NUMBER [--compact]
ptab decision download [--q Q] --out FILE.json

doc — Trial Documents

ptab doc search [--q Q] [--type TYPE] [--from DATE] [--to DATE]
ptab doc get DOC_ID
ptab doc list TRIAL_NUMBER [--category CATEGORY] [--party PARTY] [--type TYPE,TYPE,...] [--compact]
ptab doc pdf DOC_ID [--out FILE.pdf] [--md] [--doc-type TEXT]
ptab doc parse PDF_FILE [--out FILE.md] [--doc-type TEXT]
ptab doc fetch-case TRIAL_NUMBER [--types TYPE,TYPE,...] [--out-dir DIR] [--md] [--delay SECONDS]
ptab doc download [--q Q] --out FILE.json

appeal — Appeal Decisions

ptab appeal search [--q Q] [--from DATE] [--to DATE]
ptab appeal get DOC_ID
ptab appeal list APPEAL_NUMBER
ptab appeal download [--q Q] --out FILE.json

interference — Interference Decisions

ptab interference search [--q Q] [--from DATE] [--to DATE]
ptab interference get DOC_ID
ptab interference list INTERFERENCE_NUMBER
ptab interference download [--q Q] --out FILE.json

PDF → Markdown Conversion

ptab doc parse converts a downloaded PTAB PDF into structured Markdown for use with AI coding assistants or document analysis pipelines.

# Download a document as PDF, then convert to Markdown
ptab doc pdf 171200528 --out fwd.pdf
ptab doc parse fwd.pdf

# Specify a custom output path
ptab doc parse fwd.pdf --out analysis/fwd.md

# Or do both in one step
ptab doc pdf 171200528 --out fwd.pdf --md

The output .md file includes YAML front matter (trial number, patent number, document type, date) followed by the full extracted text. Image-based (scanned) pages are automatically detected — the command saves whatever text it can extract and prints a warning with the affected page numbers, the percentage of the document they represent, and — for pages that look like an Exhibit List / appendix (roman-numeral page labels or an "Exhibit List" heading) — a separate hint distinguishing them from pages that may have lost actual body text.

Note: OCR is not performed automatically. If your PDF is fully image-based, use an external OCR tool first.

Why this matters: PTAB decision PDFs use font encodings that many PDF readers — including the built-in PDF readers of AI coding agents — render as garbled, letter-spaced text (e.g. "G O O G L E LLC"). ptab doc parse (and doc pdf --md) extract the underlying text layer correctly, so always read the generated .md file instead of the raw PDF when analyzing PTAB documents with an AI agent.

The document_type recorded in the front matter is guessed from the PDF content by default, which can be wrong. Pass --doc-type to record the actual type instead (e.g. the documentTypeDescriptionText value from ptab doc list); when guessed, the front matter includes document_type_guessed: true so you know to double-check it.

ptab doc parse fwd.pdf --doc-type "Final Written Decision"
ptab doc pdf 171200528 --md --doc-type "Institution Decision: Grant"

Fetching an entire case in one command

ptab doc fetch-case downloads (and optionally converts) every document for a trial in a single call, instead of scripting a loop around doc list + doc pdf:

# Download everything for a trial
ptab doc fetch-case IPR2023-00001

# Only the key documents, converted to Markdown
ptab doc fetch-case IPR2023-00001 \
  --types "Petition,Institution Decision,Patent Owner Response,Final Written Decision" \
  --md

# Custom output directory and a longer delay between requests
ptab doc fetch-case IPR2023-00001 --out-dir cases/ipr-1 --md --delay 5

Documents are saved as {N}_{type-slug}.pdf in the target directory (default: ./{TRIAL_NUMBER}), with a configurable delay between requests to stay within rate limits. With --md, each PDF is converted immediately using the document's own documentTypeDescriptionText as --doc-type, so the front matter is accurate without guessing. A failed document is skipped (not fatal) and the command prints a final N/M saved summary.

Options

All search commands accept:

--q TEXT          Lucene query string
--from DATE       Start date (YYYY-MM-DD)
--to DATE         End date (YYYY-MM-DD)
--limit N         Maximum results (default: 25)
--offset N        Page offset (default: 0)
--sort FIELD      Sort field (e.g. "filingDate desc")
--format/-f       Output format: table | json | csv (default: table)
--out FILE        Save output to file (csv/json)
--api-key KEY     API key (one-time override)

Global options (placed immediately after ptab):

--verbose/-v      Debug HTTP request/response logs (stderr).
                  Also surfaces any response header containing "ratelimit"
                  (e.g. remaining quota), including on 429 responses.
--timeout N       Request timeout in seconds
--version         Show version

Retries with exponential backoff are built in for transient errors (429, 500, 502, 503, 504) — no need to add your own delay logic for occasional rate limiting.

Output Formats

table (default) — Terminal-friendly, key fields only:

 Trial No.       Type  Filed       Status       Petitioner        Patent No.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 IPR2023-00001   IPR   2023-01-05  Terminated   Apple Inc.        US9876543

1 results (1 total)

json — Raw API response, pretty-printed (useful for piping)

csv — CSV with headers (UTF-8 BOM, for spreadsheets and data analysis)

Examples

# Search Apple IPR filings in 2023
ptab proc search --q "petitionerPartyName:Apple" --type IPR --from 2023-01-01 --to 2023-12-31

# Get a single trial as JSON
ptab proc get IPR2023-00001 --format json

# Save Final Written Decisions to CSV
ptab decision search --type "Final Written Decision" --from 2024-01-01 --format csv --out decisions.csv

# Search decisions by petitioner name
ptab decision search --petitioner Apple --format csv --out apple_decisions.csv

# Search decisions by patent number
ptab decision search --patent US9876543

# Download Samsung IPR proceedings as JSON
ptab proc download --q "petitionerPartyName:Samsung" --type IPR --out samsung_ipr.json

# List documents for a trial
ptab doc list IPR2023-00001

# Filter documents by category (FINAL, DECISION, MOTION, Exhibit, …)
ptab doc list IPR2023-00001 --category FINAL

# Filter documents by filing party (BOARD, PETITIONER, PATENT OWNER)
ptab doc list IPR2023-00001 --party BOARD

# Combine filters
ptab doc list IPR2023-00001 --category FINAL --party BOARD

# Filter by document type (substring match, case-insensitive)
ptab doc list IPR2023-00001 --type "Institution Decision,Final Written Decision"

# Compact JSON: hoist per-trial metadata to the top level instead of
# repeating it in every item (~55% smaller for IPR2019-01238)
ptab doc list IPR2023-00001 --format json --compact
ptab decision list IPR2023-00001 --format json --compact

# Download a single document as PDF
ptab doc pdf 171200528
ptab doc pdf 171200528 --out petition.pdf

# Convert a PDF to Markdown for AI analysis
ptab doc parse petition.pdf
ptab doc parse petition.pdf --out analysis/petition.md

# Record the actual document type instead of guessing
ptab doc parse petition.pdf --doc-type "Petition"

# Fetch every key document for a case in one command
ptab doc fetch-case IPR2023-00001 --types "Petition,Institution Decision,Final Written Decision" --md

# Combine Lucene query clauses
ptab proc search --q "statusCategory:Terminated AND trialMetaData.trialTypeCode:IPR"

# Extend timeout for slow connections
ptab --timeout 60 proc search --q "petitionerPartyName:Apple"

Requirements

• Python 3.11+
• USPTO PTAB API key (obtain at developer.uspto.gov)

License

MIT