Proceedings
List Proceedings
Search trademark proceedings (oppositions, cancellations, appeals) across all marks
GET
When To Use This
Use this endpoint when you need a cross-mark view of trademark disputes, such as profiling an opponent’s history, checking whether a party usually settles or wins, or building a filtered litigation timeline for a class, office, or date window. At least one filter is required, andaggregations adds bucket maps over the exact same filtered set returned by the list query.
For an end-to-end workflow, see Opposition & Dispute Intelligence.
Query Parameters
At least one of the following must be supplied:contested_class, trademark_id, proceeding_type, status, q, party_owner_id, party_entity_id, entity_id, party_role, office_code, filed_date_gte, filed_date_lt, decision_date_gte, decision_date_lt. aggregations alone does not satisfy the filter requirement.
Nice class involved in the dispute (1-45).
Restrict to proceedings on a specific trademark (
tm_...).Type of proceeding. One of
opposition, cancellation, revocation, invalidity, appeal, non_use_removal, court_action, other.Status. One of
pending, decided_granted, decided_rejected, withdrawn, settled, suspended, partial, other.Search opponent / party name.
Filter by a party owner ID (
own_...).Filter by a resolved or derived entity ID (
ent_...). The API expands the entity to its member owner IDs and matches proceedings where any member owner is a party.Alias for
party_entity_id.Filter by party role. One of
opponent, petitioner, respondent, intervener, other.Lowercase office code (e.g.
uspto, euipo).Filed date >= (YYYY-MM-DD).
Filed date < (YYYY-MM-DD). Must be after
filed_date_gte.Decision date >= (YYYY-MM-DD).
Decision date < (YYYY-MM-DD). Must be after
decision_date_gte.Comma-separated bucket maps to include in the response. Allowed values:
outcome, party_role, nice_class, office_code, filed_year.Sort order. One of
-filed_date, filed_date, -decided_date, decided_date.Page size (1-100).
Pagination cursor from a previous response.
Response
Array of proceeding summary records.
Present when requested. Shape:
{ aggregation_name: { bucket_key: count } }.id (prc_...), trademark_id, proceeding_type, proceeding_number, status, outcome, duration_days, office_code, filed_date, decision_date, decision_outcome, contested_classes, and description. The nullable item fields are proceeding_number, status, outcome, duration_days, filed_date, decision_date, decision_outcome, contested_classes, and description (trademark_id and office_code are always present). See Get Proceeding for parties, outcome meanings, and the trademark cross-reference.
Aggregation buckets are computed in SQL over the exact filtered proceedings set. outcome, office_code, and filed_year are single-valued dimensions, so their bucket sums reconcile with the filtered list count when their values are present. nice_class counts a proceeding once per contested class, and party_role counts a proceeding once per distinct role represented in its parties, so those bucket sums can be larger than the list count.
Example Request
Example Response
Code Examples
Errors
| Status | Type | Description |
|---|---|---|
| 400 | validation_error | No filter supplied, invalid date range, or unsupported parameter value |
| 401 | unauthorized | Missing or invalid API key |
| 422 | entity_too_large | party_entity_id / entity_id resolved to more member owners than the cap (error.reason: member_owners_too_large; carries member_count / member_count_limit) |
| 429 | rate_limited | Too many requests |
Related Endpoints
- Get Proceeding: full proceeding detail
- Trademark Proceedings: proceedings scoped to one mark
- Opposition & Dispute Intelligence: workflow for profiling an opposer
- Use Case: Opposition Tracking: monitoring active disputes