> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# List Proceedings

> Search trademark proceedings (oppositions, cancellations, appeals) across all marks

## 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, and `aggregations` adds bucket maps over the exact same filtered set returned by the list query.

For an end-to-end workflow, see [Opposition & Dispute Intelligence](/guides/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.

<ParamField query="contested_class" type="integer">
  Nice class involved in the dispute (1-45).
</ParamField>

<ParamField query="trademark_id" type="string">
  Restrict to proceedings on a specific trademark (`tm_...`).
</ParamField>

<ParamField query="proceeding_type" type="string">
  Type of proceeding. One of `opposition`, `cancellation`, `revocation`, `invalidity`, `appeal`, `non_use_removal`, `court_action`, `other`.
</ParamField>

<ParamField query="status" type="string">
  Status. One of `pending`, `decided_granted`, `decided_rejected`, `withdrawn`, `settled`, `suspended`, `partial`, `other`.
</ParamField>

<ParamField query="q" type="string">
  Search opponent / party name.
</ParamField>

<ParamField query="party_owner_id" type="string">
  Filter by a party owner ID (`own_...`).
</ParamField>

<ParamField query="party_entity_id" type="string">
  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.
</ParamField>

<ParamField query="entity_id" type="string">
  Alias for `party_entity_id`.
</ParamField>

<ParamField query="party_role" type="string">
  Filter by party role. One of `opponent`, `petitioner`, `respondent`, `intervener`, `other`.
</ParamField>

<ParamField query="office_code" type="string">
  Lowercase office code (e.g. `uspto`, `euipo`).
</ParamField>

<ParamField query="filed_date_gte" type="string">
  Filed date >= (YYYY-MM-DD).
</ParamField>

<ParamField query="filed_date_lt" type="string">
  Filed date \< (YYYY-MM-DD). Must be after `filed_date_gte`.
</ParamField>

<ParamField query="decision_date_gte" type="string">
  Decision date >= (YYYY-MM-DD).
</ParamField>

<ParamField query="decision_date_lt" type="string">
  Decision date \< (YYYY-MM-DD). Must be after `decision_date_gte`.
</ParamField>

<ParamField query="aggregations" type="string">
  Comma-separated bucket maps to include in the response. Allowed values: `outcome`, `party_role`, `nice_class`, `office_code`, `filed_year`.
</ParamField>

<ParamField query="sort" type="string" default="-filed_date">
  Sort order. One of `-filed_date`, `filed_date`, `-decided_date`, `decided_date`.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Page size (1-100).
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response.
</ParamField>

## Response

<ResponseField name="data" type="object[]">
  Array of proceeding summary records.
</ResponseField>

<ResponseField name="aggregations" type="object">
  Present when requested. Shape: `{ aggregation_name: { bucket_key: count } }`.
</ResponseField>

Each item carries `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`](/api-reference/proceedings/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

<RequestExample>
  ```bash cURL theme={null}
  curl -G "https://api.signa.so/v1/proceedings" \
    -H "Authorization: Bearer $SIGNA_API_KEY" \
    --data-urlencode "party_entity_id=ent_019f34d6-3333-7777-8888-333333333333" \
    --data-urlencode "office_code=uspto" \
    --data-urlencode "aggregations=outcome,party_role,nice_class,office_code,filed_year" \
    --data-urlencode "limit=20"
  ```
</RequestExample>

## Example Response

<ResponseExample>
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "prc_019f34d6-1111-7777-8888-111111111111",
        "object": "proceeding",
        "trademark_id": "tm_019f34d6-aaaa-7777-8888-111111111111",
        "proceeding_type": "opposition",
        "proceeding_number": "91265432",
        "status": "decided_granted",
        "outcome": "challenger_won",
        "duration_days": 184,
        "office_code": "uspto",
        "filed_date": "2023-03-01",
        "decision_date": "2023-09-01",
        "decision_outcome": "Opposition Sustained",
        "contested_classes": [9, 42],
        "description": "Opposition proceeding",
        "created_at": "2023-03-01T10:00:00.000Z",
        "updated_at": "2023-09-01T10:00:00.000Z"
      },
      {
        "id": "prc_019f34d6-2222-7777-8888-222222222222",
        "object": "proceeding",
        "trademark_id": "tm_019f34d6-bbbb-7777-8888-222222222222",
        "proceeding_type": "opposition",
        "proceeding_number": "91270001",
        "status": "settled",
        "outcome": "settled",
        "duration_days": null,
        "office_code": "uspto",
        "filed_date": "2023-06-12",
        "decision_date": null,
        "decision_outcome": null,
        "contested_classes": [9],
        "description": "Opposition proceeding",
        "created_at": "2023-06-12T10:00:00.000Z",
        "updated_at": "2023-06-12T10:00:00.000Z"
      }
    ],
    "has_more": false,
    "pagination": { "cursor": null },
    "aggregations": {
      "outcome": { "challenger_won": 1, "settled": 1 },
      "party_role": { "opponent": 2, "respondent": 2 },
      "office_code": { "uspto": 2 },
      "filed_year": { "2023": 2 },
      "nice_class": { "9": 2, "42": 1 }
    },
    "request_id": "req_xyz"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/proceedings?proceeding_type=opposition&status=pending&office_code=uspto&filed_date_gte=2025-01-01&limit=20" \
    -H "Authorization: Bearer sig_YOUR_KEY_HERE"

  curl "https://api.signa.so/v1/proceedings?party_entity_id=ent_019f34d6-3333-7777-8888-333333333333&office_code=uspto&aggregations=outcome,party_role,office_code,filed_year,nice_class" \
    -H "Authorization: Bearer sig_YOUR_KEY_HERE"
  ```

  ```typescript TypeScript theme={null}
  import { Signa } from "@signa-so/sdk";

  const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });

  const page = await signa.proceedings.list({
    party_entity_id: "ent_019f34d6-3333-7777-8888-333333333333",
    office_code: "uspto",
    aggregations: ["outcome", "party_role", "office_code", "filed_year", "nice_class"],
    limit: 20,
  });
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://api.signa.so/v1/proceedings",
      headers={"Authorization": "Bearer sig_YOUR_KEY_HERE"},
      params={
          "party_entity_id": "ent_019f34d6-3333-7777-8888-333333333333",
          "office_code": "uspto",
          "aggregations": "outcome,party_role,office_code,filed_year,nice_class",
          "limit": 20,
      },
  )
  ```
</CodeGroup>

## 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](/api-reference/proceedings/get-proceeding): full proceeding detail
* [Trademark Proceedings](/api-reference/trademarks/trademark-proceedings): proceedings scoped to one mark
* [Opposition & Dispute Intelligence](/guides/opposition-dispute-intelligence): workflow for profiling an opposer
* [Use Case: Opposition Tracking](/guides/use-cases/opposition-tracking): monitoring active disputes