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

# Retrieve Proceeding

> Retrieve a single trademark proceeding with parties, classes, and decision metadata

**Credits:** 1 per record.

## When To Use This

Use this endpoint when you already have a proceeding ID and need the full dispute record for docket review, risk analysis, or client reporting. For example, an IP litigation team can fetch a decided TTAB opposition to see the parties, contested classes, office decision summary, normalized outcome, and how long the case ran.

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

A proceeding on a mark from an office whose `capabilities.proceedings` is not `available` on [List Offices](/api-reference/reference/list-offices) is not served and returns `404 not_found`.

## Path Parameters

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

## Response

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

<ResponseField name="object" type="string">
  Always `proceeding`.
</ResponseField>

<ResponseField name="trademark_id" type="string | null">
  The mark this row belongs to (`tm_...`). One proceeding has one row per linked mark; see `trademarks` for all of them.
</ResponseField>

<ResponseField name="trademark_role" type="string">
  Which side `trademark_id` is on. `contested`: the proceeding targets this mark (opposed application, registration under cancellation, appealed application). `asserted`: the opposer or petitioner pleaded this mark as a prior right.
</ResponseField>

<ResponseField name="proceeding_type" type="string">
  Type (`opposition`, `cancellation`, `appeal`, etc.).
</ResponseField>

<ResponseField name="proceeding_number" type="string | null">
  Office-issued proceeding identifier, when available. For CIPO, `proceeding_number` is the office's per-record sequence identifier (1, 2, ...), not a Board docket number.
</ResponseField>

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

<ResponseField name="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. Most ended US (TTAB) cases read `other`, because Signa does not yet read how a terminated TTAB case ended. |

<Note>
  **US (TTAB) dates.** `filed_date` is set on about 99% of US oppositions and cancellations, loaded from the USPTO TTAB bulk feed. Ex parte appeals do not carry a filing date yet. `decision_date` is set on only a small share of US rows, so `duration_days` is usually `null` for TTAB rows. Treat a null date as "not yet loaded", not "unknown to the USPTO".
</Note>

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

<ResponseField name="office_code" type="string | null">
  Uppercase WIPO ST.3 office code for the parent trademark (e.g. `US`, `EM`), when available.
</ResponseField>

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

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

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

<ResponseField name="parties" type="object[]">
  Array of parties. Each has `owner_id`, `name`, `role` (`opponent`, `petitioner`, `respondent`, `intervener`, `other`), and `country_code`. `owner_id` is the owner Signa linked the party to, reported as its current owner record (if that owner has since been merged into another, the surviving owner), or `null` when the party is not linked.
</ResponseField>

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

<ResponseField name="description" type="string | null">
  Free-text summary, when provided.
</ResponseField>

<ResponseField name="trademark" type="object | null">
  Summary of the mark this row belongs to (`id`, `object`, `mark_text`, `application_number`, `office_code`, `trademark_role`), or `null` when unavailable.
</ResponseField>

<ResponseField name="trademarks" type="object[]">
  Every mark linked to this proceeding in the same office, type and proceeding number, each with the same shape as `trademark`. Includes `trademark`. For a TTAB opposition this puts the opposed application (`contested`) next to the registrations the opposer pleaded (`asserted`) in one response. A placeholder row without a proceeding number links only itself.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO timestamp for when Signa created the proceeding record.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO timestamp for the latest Signa update to the proceeding record.
</ResponseField>

## Example Request

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/proceedings/prc_019f34d6-aaaa-7777-8888-aaaaaaaaaaaa" \
    -H "Authorization: Bearer $SIGNA_API_KEY"
  ```
</RequestExample>

## Example Response

<ResponseExample>
  ```json theme={null}
  {
    "id": "prc_019f34d6-aaaa-7777-8888-aaaaaaaaaaaa",
    "object": "proceeding",
    "trademark_id": "tm_019f34d6-2000-7777-8888-000000000001",
    "trademark_role": "contested",
    "proceeding_type": "opposition",
    "proceeding_number": "91265432",
    "status": "decided_granted",
    "outcome": "challenger_won",
    "duration_days": 231,
    "office_code": "US",
    "filed_date": "2024-01-18",
    "decision_date": "2024-09-05",
    "decision_outcome": "Opposition Sustained",
    "contested_classes": [9, 42],
    "description": "Opposition proceeding",
    "created_at": "2024-01-18T10:00:00.000Z",
    "updated_at": "2024-09-05T10:00:00.000Z",
    "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"
      }
    ],
    "trademark": {
      "id": "tm_019f34d6-2000-7777-8888-000000000001",
      "object": "trademark",
      "mark_text": "MERIDIAN CORE",
      "application_number": "98123456",
      "office_code": "US",
      "trademark_role": "contested"
    },
    "trademarks": [
      {
        "id": "tm_019f34d6-1000-7777-8888-000000000009",
        "object": "trademark",
        "mark_text": "APEX",
        "application_number": "87654321",
        "office_code": "US",
        "trademark_role": "asserted"
      },
      {
        "id": "tm_019f34d6-2000-7777-8888-000000000001",
        "object": "trademark",
        "mark_text": "MERIDIAN CORE",
        "application_number": "98123456",
        "office_code": "US",
        "trademark_role": "contested"
      }
    ],
    "request_id": "req_xyz"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/proceedings/prc_019f34d6-aaaa-7777-8888-aaaaaaaaaaaa" \
    -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 proceeding = await signa.proceedings.retrieve("prc_019f34d6-aaaa-7777-8888-aaaaaaaaaaaa");
  ```

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

  resp = requests.get(
      "https://api.signa.so/v1/proceedings/prc_019f34d6-aaaa-7777-8888-aaaaaaaaaaaa",
      headers={"Authorization": "Bearer sig_YOUR_KEY_HERE"},
  )
  ```
</CodeGroup>

## Related Endpoints

* [Search Proceedings](/api-reference/proceedings/search-proceedings): search proceedings with filters
* [Trademark Proceedings](/api-reference/trademarks/trademark-proceedings): proceedings scoped to a mark
* [Opposition & Dispute Intelligence](/guides/opposition-dispute-intelligence): workflow for profiling an opposer


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.