PTAB Trials Client

clients.ptab_trials - Client for USPTO PTAB Trials API.

This module provides a client for interacting with the USPTO PTAB (Patent Trial and Appeal Board) Trials API. It allows you to search for trial proceedings, documents, and decisions.

class pyUSPTO.clients.ptab_trials.PTABTrialsClient(config=None, base_url=None)[source]

Bases: BaseUSPTOClient[PTABTrialProceedingResponse | PTABTrialDocumentResponse]

Client for interacting with the USPTO PTAB Trials API.

This client provides methods to search for trial proceedings, trial documents, and trial decisions from the Patent Trial and Appeal Board.

Trial proceedings data includes IPR (Inter Partes Review), PGR (Post-Grant Review), CBM (Covered Business Method), and DER (Derivation) proceedings.

ENDPOINTS = {'search_decisions': 'api/v1/patent/trials/decisions/search', 'search_documents': 'api/v1/patent/trials/documents/search', 'search_proceedings': 'api/v1/patent/trials/proceedings/search'}
__init__(config=None, base_url=None)[source]

Initialize the PTABTrialsClient.

Parameters:

  • config (Optional[USPTOConfig]) – USPTOConfig instance containing API key and settings. If not provided, creates config from environment variables (requires USPTO_API_KEY).

  • base_url (Optional[str]) – Optional base URL override for the USPTO PTAB API. If not provided, uses config.ptab_base_url or default.

download_trial_archive(trial_meta_data, destination=None, file_name=None, overwrite=False)[source]

Download trial archive (ZIP/TAR) without extraction.

Parameters:

  • trial_meta_data (TrialMetaData) – TrialMetaData with file_download_uri

  • destination (Optional[str]) – Directory to save to

  • file_name (Optional[str]) – Override filename

  • overwrite (bool) – Overwrite existing file

Return type:

str

Returns:

Path to downloaded archive file

Raises:

ValueError – If trial_meta_data has no file_download_uri

download_trial_document(document_data, destination=None, file_name=None, overwrite=False)[source]

Download individual trial document (auto-extracts if needed).

Parameters:

  • document_data (TrialDocumentData) – TrialDocumentData with file_download_uri

  • destination (Optional[str]) – Directory to save to

  • file_name (Optional[str]) – Override filename

  • overwrite (bool) – Overwrite existing file

Return type:

str

Returns:

Path to downloaded file

Raises:

ValueError – If document_data has no file_download_uri

download_trial_documents(trial_meta_data, destination=None, overwrite=False)[source]

Download and extract all trial documents.

Parameters:

  • trial_meta_data (TrialMetaData) – TrialMetaData with file_download_uri

  • destination (Optional[str]) – Directory to save/extract to

  • overwrite (bool) – Overwrite existing files

Return type:

str

Returns:

Path to extraction directory

Raises:

ValueError – If trial_meta_data has no file_download_uri

paginate_proceedings(post_body=None, **kwargs)[source]

Provide an iterator to paginate through trial proceeding search results.

Supports both GET and POST requests.

Parameters:

  • post_body (Optional[dict[str, Any]]) – Optional POST body for complex search queries

  • **kwargs (Any) – Keyword arguments for GET-based pagination

Yields:

PTABTrialProceeding objects

Return type:

Iterator[PTABTrialProceeding]

search_decisions(query=None, sort=None, offset=0, limit=25, facets=None, fields=None, filters=None, range_filters=None, post_body=None, trial_number_q=None, decision_type_category_q=None, document_type_description_q=None, decision_date_from_q=None, decision_date_to_q=None, trial_type_code_q=None, patent_number_q=None, application_number_q=None, patent_owner_name_q=None, trial_status_category_q=None, real_party_in_interest_name_q=None, document_category_q=None, additional_query_params=None)[source]

Search for PTAB trial decisions.

This method can perform either a GET request using query parameters or a POST request if post_body is specified. When using GET, you can provide either a direct query string or use convenience parameters that will be automatically combined into a query.

Parameters:

  • query (Optional[str]) – Direct query string in USPTO search syntax.

  • sort (Optional[str]) – Sort order for results.

  • offset (int | None) – Number of records to skip (pagination).

  • limit (int | None) – Maximum number of records to return.

  • facets (Optional[str]) – Facet configuration string.

  • fields (Optional[str]) – Specific fields to return.

  • filters (Optional[str]) – Filter configuration string.

  • range_filters (Optional[str]) – Range filter configuration string.

  • post_body (Optional[dict[str, Any]]) – Optional POST body for complex queries.

  • trial_number_q (Optional[str]) – Filter by trial number.

  • decision_type_category_q (Optional[str]) – Filter by decision type category.

  • document_type_description_q (Optional[str]) – Filter by “[description]”.

  • decision_date_from_q (Optional[str]) – Filter decisions from this date (YYYY-MM-DD).

  • decision_date_to_q (Optional[str]) – Filter decisions to this date (YYYY-MM-DD).

  • trial_type_code_q (Optional[str]) – Filter by trial type code (e.g., “IPR”, “PGR”, “CBM”, “DER”).

  • patent_number_q (Optional[str]) – Filter by patent number.

  • application_number_q (Optional[str]) – Filter by application number.

  • patent_owner_name_q (Optional[str]) – Filter by patent owner name.

  • trial_status_category_q (Optional[str]) – Filter by trial status category.

  • real_party_in_interest_name_q (Optional[str]) – Filter by real party in interest name.

  • document_category_q (Optional[str]) – Filter by document category.

  • additional_query_params (Optional[dict[str, Any]]) – Additional custom query parameters.

Returns:

Response containing matching trial decisions.

Return type:

PTABTrialDocumentResponse

Examples

# Search with direct query >>> response = client.search_decisions(query=”trialNumber:IPR2023-00001”)

# Search with convenience parameters >>> response = client.search_decisions( … decision_type_category_q=”Final Written Decision”, … decision_date_from_q=”2023-01-01”, … limit=50 … )

search_documents(query=None, sort=None, offset=0, limit=25, facets=None, fields=None, filters=None, range_filters=None, post_body=None, trial_number_q=None, document_category_q=None, document_type_name_q=None, filing_date_from_q=None, filing_date_to_q=None, petitioner_real_party_in_interest_name_q=None, inventor_name_q=None, real_party_in_interest_name_q=None, patent_number_q=None, patent_owner_name_q=None, additional_query_params=None)[source]

Search for PTAB trial documents.

This method can perform either a GET request using query parameters or a POST request if post_body is specified. When using GET, you can provide either a direct query string or use convenience parameters that will be automatically combined into a query.

Parameters:

  • query (Optional[str]) – Direct query string in USPTO search syntax.

  • sort (Optional[str]) – Sort order for results.

  • offset (int | None) – Number of records to skip (pagination).

  • limit (int | None) – Maximum number of records to return.

  • facets (Optional[str]) – Facet configuration string.

  • fields (Optional[str]) – Specific fields to return.

  • filters (Optional[str]) – Filter configuration string.

  • range_filters (Optional[str]) – Range filter configuration string.

  • post_body (Optional[dict[str, Any]]) – Optional POST body for complex queries.

  • trial_number_q (Optional[str]) – Filter by trial number.

  • document_category_q (Optional[str]) – Filter by document category (e.g., “Petition”) DOCUMENTED BUT NOT IN API.

  • document_type_name_q (Optional[str]) – Filter by document type name (description).

  • filing_date_from_q (Optional[str]) – Filter documents from this date (YYYY-MM-DD).

  • filing_date_to_q (Optional[str]) – Filter documents to this date (YYYY-MM-DD).

  • petitioner_real_party_in_interest_name_q (Optional[str]) – Filter by petitioner real party in interest.

  • inventor_name_q (Optional[str]) – Filter by inventor name.

  • real_party_in_interest_name_q (Optional[str]) – Filter by real party in interest (generic).

  • patent_number_q (Optional[str]) – Filter by patent number.

  • patent_owner_name_q (Optional[str]) – Filter by patent owner name.

  • additional_query_params (Optional[dict[str, Any]]) – Additional custom query parameters.

Returns:

Response containing matching trial documents.

Return type:

PTABTrialDocumentResponse

Examples

# Search with direct query >>> response = client.search_documents(query=”trialNumber:IPR2023-00001”)

# Search with convenience parameters >>> response = client.search_documents( … document_category_q=”Paper”, … filing_date_from_q=”2023-01-01”, … limit=50 … )

search_proceedings(query=None, sort=None, offset=0, limit=25, facets=None, fields=None, filters=None, range_filters=None, post_body=None, trial_number_q=None, patent_owner_name_q=None, petitioner_real_party_in_interest_name_q=None, respondent_name_q=None, trial_type_code_q=None, trial_status_category_q=None, petition_filing_date_from_q=None, petition_filing_date_to_q=None, additional_query_params=None)[source]

Search for PTAB trial proceedings.

This method can perform either a GET request using query parameters or a POST request if post_body is specified. When using GET, you can provide either a direct query string or use convenience parameters that will be automatically combined into a query.

Parameters:

  • query (Optional[str]) – Direct query string in USPTO search syntax.

  • sort (Optional[str]) – Sort order for results.

  • offset (int | None) – Number of records to skip (pagination).

  • limit (int | None) – Maximum number of records to return.

  • facets (Optional[str]) – Facet configuration string.

  • fields (Optional[str]) – Specific fields to return.

  • filters (Optional[str]) – Filter configuration string.

  • range_filters (Optional[str]) – Range filter configuration string.

  • post_body (Optional[dict[str, Any]]) – Optional POST body for complex queries.

  • trial_number_q (Optional[str]) – Filter by trial number (e.g., “IPR2023-00001”).

  • patent_owner_name_q (Optional[str]) – Filter by patent owner name.

  • petitioner_real_party_in_interest_name_q (Optional[str]) – Filter by petitioner real party in interest.

  • respondent_name_q (Optional[str]) – Filter by respondent name.

  • trial_type_code_q (Optional[str]) – Filter by trial type code (e.g., “IPR”, “PGR”, “CBM”, “DER”).

  • trial_status_category_q (Optional[str]) – Filter by trial status category.

  • petition_filing_date_from_q (Optional[str]) – Filter proceedings from this date (YYYY-MM-DD).

  • petition_filing_date_to_q (Optional[str]) – Filter proceedings to this date (YYYY-MM-DD).

  • additional_query_params (Optional[dict[str, Any]]) – Additional custom query parameters.

Returns:

Response containing matching trial proceedings.

Return type:

PTABTrialProceedingResponse

Examples

# Search with direct query >>> response = client.search_proceedings(query=”trialNumber:IPR2023-00001”)

# Search with convenience parameters >>> response = client.search_proceedings( … trial_type_code_q=”IPR”, … petition_filing_date_from_q=”2023-01-01”, … limit=50 … )