> ## 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 History
> Paginated prosecution event timeline for a trademark
## Overview
Returns the prosecution event timeline for a trademark, sourced from office records and normalized. Events cover filings, examinations, publications, registrations, renewals, assignments, oppositions, status changes, and ad-hoc letters from the office.
Each event carries the canonical Signa `event_type`, the office's raw code and label, the event scope (right, class, designation, proceeding, or other), and an optional `status_after_event` snapshot. Use it to build prosecution timelines, audit ownership transfers, and reconcile renewal cycles.
Results are paginated and returned in reverse chronological order (newest first).
## Path Parameters
Trademark ID prefixed with `tm_` (e.g. `tm_8kLm2nPq`).
## Query Parameters
Filter by one or more canonical event type codes, comma-separated. Example: `event_type=registration,renewal`. Use the [List Event Types](/api-reference/reference/list-event-types) endpoint for the full enum.
Filter by event scope. One of `right`, `class`, `designation`, `proceeding`, `other`.
Earliest event date (inclusive), ISO `YYYY-MM-DD`.
Latest event date (exclusive), ISO `YYYY-MM-DD`.
Page size, between 1 and 100.
Opaque cursor returned in the previous response's `pagination.cursor`.
## Response
Always `list`.
Event ID prefixed with `evt_` (e.g. `evt_550e8400-e29b-41d4-a716-446655440000`).
Always `event`.
ISO date when the event occurred.
Canonical Signa event type code.
Human-readable description.
Office-native event code as received from the source.
Office-native event label as received from the source.
Scope of the event: `right`, `class`, `designation`, `proceeding`, or `other`. May be `null` for many events — not all events have a scope assigned.
Status stage of the mark immediately after this event, when the office reports it.
Nice class number when the event is class-scoped.
Designated territory code when the event is designation-scoped.
Office-side identifier for the event (e.g. action key, gazette reference).
Office-assigned sequence number used to deduplicate events on the same date.
Whether more events are available.
Cursor for the next page.
Unique request identifier for support and debugging.
```json Response theme={null}
{
"object": "list",
"data": [
{
"id": "evt_550e8400-e29b-41d4-a716-446655440000",
"object": "event",
"event_date": "2024-09-18",
"event_type": "registration",
"description": "Registration certificate issued",
"raw_code": "RN",
"raw_label": "REGISTERED",
"event_scope": "right",
"status_after_event": "registered",
"nice_class_number": null,
"territory_code": null,
"source_identifier": "uspto-statusview-2024-09-18",
"sequence_no": 1
},
{
"id": "evt_7d4e1f2a-3b8c-4d0e-9f1a-2b3c4d5e6f7a",
"object": "event",
"event_date": "2024-02-06",
"event_type": "publication",
"description": "Published for opposition",
"raw_code": "PB",
"raw_label": "PUBLISHED FOR OPPOSITION",
"event_scope": "right",
"status_after_event": "published",
"nice_class_number": null,
"territory_code": null,
"source_identifier": null,
"sequence_no": 1
},
{
"id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"object": "event",
"event_date": "2023-04-12",
"event_type": "filing",
"description": "Application filed",
"raw_code": "NA",
"raw_label": "NEW APPLICATION",
"event_scope": null,
"status_after_event": "filed",
"nice_class_number": null,
"territory_code": null,
"source_identifier": null,
"sequence_no": 1
}
],
"has_more": false,
"pagination": {
"cursor": null
},
"request_id": "req_cV2nL8pQ"
}
```
## Code Examples
```bash cURL theme={null}
curl -G "https://api.signa.so/v1/trademarks/tm_8kLm2nPq/history" \
-H "Authorization: Bearer sig_YOUR_KEY_HERE" \
--data-urlencode "event_type=registration,renewal" \
--data-urlencode "limit=20"
```
```python Python theme={null}
import requests
resp = requests.get(
"https://api.signa.so/v1/trademarks/tm_8kLm2nPq/history",
headers={"Authorization": "Bearer sig_YOUR_KEY_HERE"},
params={"event_type": "registration,renewal", "limit": 20},
)
events = resp.json()["data"]
```
```typescript TypeScript theme={null}
import { Signa } from "@signa-so/sdk";
const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });
const history = await signa.trademarks.history("tm_8kLm2nPq", {
event_type: "registration,renewal",
limit: 20,
});
for await (const event of history) {
console.log(event.event_date, event.event_type, event.description);
}
```
## Errors
| Status | Type | Description |
| ------ | ------------------ | ------------------------------------------------------------------------------------- |
| 400 | `validation_error` | Invalid `id` format, malformed date, or `event_date_gte` greater than `event_date_lt` |
| 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
* [Get Trademark](/api-reference/trademarks/get-trademark) -- current trademark data (the `?include=history` parameter is not supported on the detail endpoint; use this sub-resource endpoint to fetch event history)
* [List Event Types](/api-reference/reference/list-event-types) -- canonical event type enum
* [Trademark Changes](/api-reference/trademarks/trademark-changes) -- version-level field-by-field change log