> ## 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 Cited By

> Applications an examiner cited this mark against, the refusals where this mark is the prior right

## When To Use This

Use this endpoint to measure how much of a blocker a mark is. Each row is one citation occurrence: this mark named as the prior right in one office action against one application. This is the outbound direction, so the marks in `trademark` are other people's applications, and the mark in the path is the reference the examiner reached for.

It answers questions a search index cannot: whether the office has actually treated this mark as a bar, how often, how recently, and whether those refusals stuck.

<Warning>
  **Rows are citation occurrences, not applications.** One application cited in both a nonfinal and a final office action produces two rows for the same mark. To count distinct applications, group by `trademark.id`, falling back to `application_ref` when `trademark` is `null`. A raw row count overstates how many applications this mark has blocked.
</Warning>

For the inbound direction, the prior marks cited against this application, use [Trademark Citations](/api-reference/trademarks/trademark-citations).

<Note>
  **Coverage today is USPTO only.** Citations are extracted from USPTO office actions and cover §2(d) likelihood-of-confusion refusals. Other offices return an empty list. Check `capabilities.citations` on [List Offices](/api-reference/reference/list-offices) to see the state of any office programmatically, rather than inferring coverage from an empty response.
</Note>

## Freshness

Citations are extracted hourly from stored office actions. Dispositions are recomputed once a day, so a newly extracted citation carries `disposition: null` until the next daily refresh, which can be up to about 24 hours. A disposition can also change on a later run as prosecution continues. `disposition_as_of` is stamped when the current disposition was first derived or last changed, and deliberately does not move when a daily run re-derives the same value. An unchanged timestamp means the disposition has been stable, not that the refresh stopped running.

## Rows Matched By Reference

Examiners cite an application or registration number. Signa resolves that number to a mark on the register at extraction time, but some rows never resolve: the cited number may belong to a mark Signa does not hold, or the mark may have been ingested after its citations were extracted.

This endpoint returns those rows too. It matches on the resolved link, and additionally on this mark's own application and registration numbers for unlinked citations from the same office, so a citation that names your number is returned even when the extraction pipeline never linked it. On such a row `cited_trademark` is `null` and `cited_ref` carries the number the examiner printed.

Treat `cited_trademark: null` as "matched by reference only", not as a missing field. Dropping those rows undercounts how often the mark has been used as a bar.

## Path Parameters

<ParamField path="id" type="string" required>
  Trademark ID (`tm_...`). This is the cited prior mark.
</ParamField>

## Query Parameters

<ParamField query="disposition" type="string">
  Filter by how the citation resolved, comma-separated. One or more of `citation_issued`, `maintained`, `withdrawn`, `abandoned_after`, `published`. Rows whose disposition has not been computed yet are excluded when this filter is supplied.
</ParamField>

<ParamField query="action_stage" type="string">
  Filter by the stage the citation reached, comma-separated. One or both of `nonfinal`, `final`. `final` includes citations first raised in a nonfinal action that a later final action maintained.
</ParamField>

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

<ParamField query="cursor" type="string">
  Opaque cursor from the previous response's `pagination.cursor`.
</ParamField>

Results are ordered by `action_date` descending, newest first, with undated actions last and `id` as the final tiebreaker. The order is fixed: there is no `sort` parameter.

## Response

The object is identical to the one returned by [Trademark Citations](/api-reference/trademarks/trademark-citations), read in the other direction: `trademark` is the citing application and `cited_trademark` is the mark in the path, or `null` on a reference-matched row.

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

<ResponseField name="data" type="object[]">
  <Expandable title="Citation object">
    <ResponseField name="id" type="string">Citation ID (`cit_...`).</ResponseField>
    <ResponseField name="object" type="string">Always `citation`.</ResponseField>
    <ResponseField name="office_code" type="string | null">Office that issued the action, uppercase ST.3 (e.g. `US`).</ResponseField>
    <ResponseField name="application_ref" type="string">Application number the office action was issued against, as printed by the office.</ResponseField>
    <ResponseField name="trademark" type="object | null">Summary of the citing application (`id`, `mark_text`, `office_code`, `application_number`, `registration_number`, `status_primary`). `null` when the citation carries no persisted link to a Signa record for that application, which is not the same as the application being absent from the register: resolution runs once, at extraction time.</ResponseField>
    <ResponseField name="cited_ref" type="string">The reference the examiner cited. On this endpoint it is this mark's application or registration number.</ResponseField>
    <ResponseField name="cited_ref_type" type="string">Whether `cited_ref` is a `registration` or an `application` number.</ResponseField>
    <ResponseField name="cited_trademark" type="object | null">Summary of the cited mark. `null` on a row matched by reference only, as described above.</ResponseField>
    <ResponseField name="refusal_type" type="string">Office-local refusal ground. `2d` is the USPTO §2(d) likelihood-of-confusion ground.</ResponseField>
    <ResponseField name="action_date" type="string | null">ISO date of the office action (`YYYY-MM-DD`).</ResponseField>
    <ResponseField name="action_stage" type="string | null">`nonfinal` or `final`. This is the stage the citation reached, not provenance about `source_document_id`. A citation first raised in a nonfinal action reads `final` once a later dated final action maintained the refusal, so `final` does not mean the row was extracted from a final action.</ResponseField>
    <ResponseField name="disposition" type="string | null">How the citation resolved. See [Disposition Values](/api-reference/trademarks/trademark-citations#disposition-values). `null` while pending the daily refresh.</ResponseField>
    <ResponseField name="disposition_as_of" type="string | null">ISO 8601 timestamp of when the current `disposition` was first derived or last changed. It does not advance when a daily run re-derives the same value, so a stale-looking timestamp means the disposition has been stable.</ResponseField>
    <ResponseField name="source_document_id" type="string | null">The office action the citation was extracted from (`med_...`), retrievable through [Trademark Documents](/api-reference/trademarks/records/documents) on the citing mark. Every citation served today carries one. The field is nullable so a citation derived without a stored source document can be represented. Documents are only addressable under a trademark, so when `trademark` is `null` there is no route that resolves this id.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">Whether more rows are available.</ResponseField>
<ResponseField name="pagination" type="object">Cursor for the next page.</ResponseField>
<ResponseField name="request_id" type="string">Unique request identifier for support and debugging.</ResponseField>

## Example Request

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/trademarks/tm_8kLm2nPq/cited-by?limit=20" \
    -H "Authorization: Bearer $SIGNA_API_KEY"
  ```
</RequestExample>

## Example Response

The second row was matched by reference: the examiner cited registration `5567890`, and that citation is returned even though the extraction pipeline never linked it to a record.

<ResponseExample>
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "cit_0198c2f1-7e2a-7b34-9c11-3d5f8a2b4c6e",
        "object": "citation",
        "office_code": "US",
        "application_ref": "98123456",
        "trademark": {
          "id": "tm_019f34d6-2000-7777-8888-000000000001",
          "mark_text": "ACME BREW",
          "office_code": "US",
          "application_number": "98123456",
          "registration_number": null,
          "status_primary": "pending"
        },
        "cited_ref": "5567890",
        "cited_ref_type": "registration",
        "cited_trademark": {
          "id": "tm_8kLm2nPq",
          "mark_text": "ACME",
          "office_code": "US",
          "application_number": "87999999",
          "registration_number": "5567890",
          "status_primary": "active"
        },
        "refusal_type": "2d",
        "action_date": "2026-01-15",
        "action_stage": "final",
        "disposition": "maintained",
        "disposition_as_of": "2026-08-30T13:30:00.000Z",
        "source_document_id": "med_0198c2f1-7e2a-7b34-9c11-3d5f8a2b4c6e"
      },
      {
        "id": "cit_0198c2f1-7e2a-7b34-9c11-3d5f8a2b4c6f",
        "object": "citation",
        "office_code": "US",
        "application_ref": "97654321",
        "trademark": {
          "id": "tm_019f34d6-3000-7777-8888-000000000002",
          "mark_text": "ACMEE",
          "office_code": "US",
          "application_number": "97654321",
          "registration_number": null,
          "status_primary": "inactive"
        },
        "cited_ref": "5567890",
        "cited_ref_type": "registration",
        "cited_trademark": null,
        "refusal_type": "2d",
        "action_date": "2025-06-02",
        "action_stage": "nonfinal",
        "disposition": "abandoned_after",
        "disposition_as_of": "2026-08-30T13:30:00.000Z",
        "source_document_id": "med_0198c2f1-7e2a-7b34-9c11-3d5f8a2b4c70"
      }
    ],
    "has_more": false,
    "pagination": { "cursor": null },
    "request_id": "req_cV2nL8pQ"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://api.signa.so/v1/trademarks/tm_8kLm2nPq/cited-by" \
    -H "Authorization: Bearer sig_YOUR_KEY_HERE" \
    --data-urlencode "disposition=maintained,abandoned_after" \
    --data-urlencode "limit=20"
  ```

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

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

  const citedBy = await signa.trademarks.citedBy("tm_8kLm2nPq", { limit: 20 });

  for (const citation of citedBy.data) {
    // `trademark` is the application that was refused over this mark.
    const blocked = citation.trademark?.mark_text ?? citation.application_ref;
    console.log(citation.action_date, blocked, citation.disposition);
  }
  ```

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

  resp = requests.get(
      "https://api.signa.so/v1/trademarks/tm_8kLm2nPq/cited-by",
      headers={"Authorization": "Bearer sig_YOUR_KEY_HERE"},
      params={"disposition": "maintained,abandoned_after", "limit": 20},
  )
  ```
</CodeGroup>

## Errors

| Status | Type               | Description                                                                      |
| ------ | ------------------ | -------------------------------------------------------------------------------- |
| 400    | `validation_error` | Malformed `id` (not a prefixed ID), unknown query parameter, or bad enum value   |
| 400    | `id_type_mismatch` | `id` is a well-formed ID of another type (e.g. `own_...`) rather than a `tm_...` |
| 400    | `cursor_expired`   | Cursor is blank, expired, or was issued for a different endpoint                 |
| 401    | `unauthorized`     | Missing or invalid API key                                                       |
| 403    | `forbidden`        | API key lacks the `trademarks:read` scope                                        |
| 404    | `not_found`        | Trademark ID does not exist                                                      |
| 429    | `rate_limited`     | Rate limit exceeded                                                              |

## Related Endpoints

* [Trademark Citations](/api-reference/trademarks/trademark-citations): prior marks cited against this application
* [Search Citations](/api-reference/citations/search-citations): cross-mark citation query with office, date, and disposition filters
* [Retrieve Trademark](/api-reference/trademarks/retrieve-trademark): parent mark detail
* [Use Case: Trademark Clearance](/guides/use-cases/trademark-clearance): where citation history fits in a clearance workflow