> ## 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.

# Trademark Proceedings

> Oppositions, cancellations, appeals, and other contested proceedings involving a trademark

## When To Use This

Use this endpoint when you are reviewing one trademark and need the dispute history attached to that mark. For example, a portfolio analyst can open a high-value mark and see every opposition or cancellation, who was involved, whether the challenger won, and how long decided cases took.

For an end-to-end workflow, see [Opposition & Dispute Intelligence](/guides/opposition-dispute-intelligence).

## Path Parameters

<ParamField path="id" type="string" required>
  Trademark ID (`tm_...`).
</ParamField>

## Query Parameters

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

<ParamField query="status" type="string">
  Filter by status. One of `pending`, `decided_granted`, `decided_rejected`, `withdrawn`, `settled`, `suspended`, `partial`, `other`.
</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 records.
</ResponseField>

<ResponseField name="data[].id" type="string">
  Proceeding ID (`prc_...`).
</ResponseField>

<ResponseField name="data[].proceeding_type" type="string">
  Type of proceeding.
</ResponseField>

<ResponseField name="data[].proceeding_number" type="string | null">
  Office-issued proceeding identifier when available.
</ResponseField>

<ResponseField name="data[].status" type="string | null">
  Current status, when available.
</ResponseField>

<ResponseField name="data[].outcome" type="string | null">
  Normalized outcome from the challenger perspective, or `null` when not available.
</ResponseField>

| Value              | Meaning                                                            |
| ------------------ | ------------------------------------------------------------------ |
| `challenger_won`   | The challenger prevailed, derived from `decided_granted`.          |
| `challenger_lost`  | The challenger did not prevail, derived from `decided_rejected`.   |
| `mixed`            | The decision was partial or text indicates an in-part disposition. |
| `settled`          | The proceeding status is `settled`.                                |
| `withdrawn`        | The proceeding status is `withdrawn`.                              |
| `default_judgment` | The challenger won through a default or procedural failure signal. |
| `pending`          | The proceeding is still `pending` or `suspended`.                  |
| `other`            | The status is `other` or does not map to a more specific outcome.  |

<ResponseField name="data[].duration_days" type="integer | null">
  Number of days between `filed_date` and `decision_date`. `null` when either date is missing.
</ResponseField>

<ResponseField name="data[].filed_date" type="string | null">
  ISO date the proceeding was initiated, when available.
</ResponseField>

<ResponseField name="data[].decision_date" type="string | null">
  ISO date of the decision when concluded, when available.
</ResponseField>

<ResponseField name="data[].decision_outcome" type="string | null">
  Outcome string when decided.
</ResponseField>

<ResponseField name="data[].parties" type="object[]">
  Array of parties to the proceeding. Each party has `owner_id`, `name`, `role` (`opponent`, `petitioner`, `respondent`, `intervener`, `other`), and `country_code`.
</ResponseField>

<ResponseField name="data[].contested_classes" type="integer[] | null">
  Nice classes contested in the proceeding, when known.
</ResponseField>

<ResponseField name="data[].description" type="string | null">
  Free-text summary, when provided by the office.
</ResponseField>

## Example Request

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/trademarks/tm_019f34d6-2000-7777-8888-000000000001/proceedings?proceeding_type=opposition&limit=20" \
    -H "Authorization: Bearer $SIGNA_API_KEY"
  ```
</RequestExample>

## Example Response

<ResponseExample>
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "prc_019f34d6-aaaa-7777-8888-aaaaaaaaaaaa",
        "proceeding_type": "opposition",
        "proceeding_number": "91265432",
        "status": "decided_granted",
        "outcome": "challenger_won",
        "duration_days": 231,
        "filed_date": "2024-01-18",
        "decision_date": "2024-09-05",
        "decision_outcome": "Opposition Sustained",
        "parties": [
          {
            "owner_id": "own_019f34d6-1111-7777-8888-111111111111",
            "name": "Apex Outdoor Group LLC",
            "role": "opponent",
            "country_code": "US"
          },
          {
            "owner_id": "own_019f34d6-2222-7777-8888-222222222222",
            "name": "Meridian Labs Inc.",
            "role": "respondent",
            "country_code": "US"
          }
        ],
        "contested_classes": [9, 42],
        "description": "Opposition proceeding"
      }
    ],
    "has_more": false,
    "pagination": { "cursor": null },
    "request_id": "req_abc"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/trademarks/tm_019f34d6-2000-7777-8888-000000000001/proceedings?proceeding_type=opposition&status=pending" \
    -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 proceedings = await signa.trademarks.proceedings("tm_019f34d6-2000-7777-8888-000000000001", {
    proceeding_type: "opposition",
    status: "pending",
  });
  ```

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

  resp = requests.get(
      "https://api.signa.so/v1/trademarks/tm_019f34d6-2000-7777-8888-000000000001/proceedings",
      headers={"Authorization": "Bearer sig_YOUR_KEY_HERE"},
      params={"proceeding_type": "opposition", "status": "pending"},
  )
  ```
</CodeGroup>

## Errors

| Status | Type               | Description                             |
| ------ | ------------------ | --------------------------------------- |
| 400    | `validation_error` | Invalid query parameter or trademark ID |
| 401    | `unauthorized`     | Missing or invalid API key              |
| 404    | `not_found`        | Trademark not found                     |
| 429    | `rate_limited`     | Too many requests                       |

## Related Endpoints

* [List Proceedings](/api-reference/proceedings/list-proceedings): search proceedings across all marks
* [Get Proceeding](/api-reference/proceedings/get-proceeding): full detail for a single proceeding
* [Get Trademark](/api-reference/trademarks/get-trademark): parent trademark detail
* [Opposition & Dispute Intelligence](/guides/opposition-dispute-intelligence): workflow for profiling an opposer