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

# How records change

> When a record counts as changed, how changes reach the API, and the bursts and reloads an integration must expect.

## What counts as a change

A record changes when its stored content changes. That happens when:

* the office publishes something new about the mark: a status, a date, a new owner;
* Pinakel processes the record differently, for example after improving a mapping or the name normalization;
* the register is reloaded from its source.

`updated_at` is the time of the last change in Pinakel, not the date of the office's event. The office's own dates are in `dates` and `status.date`.

## How changes reach you

Each register is checked on its own schedule (`update_frequency` in [`GET /v1/jurisdictions`](https://docs.pinakelai.com/api-reference/jurisdictions/list)). After an update is loaded, the changed records are published to the [changes feed](https://docs.pinakelai.com/guides/syncing.md) in batches. Each feed item is published once per change, with a `created_at` timestamp (the publication time), and carries the record as it is when you read the page.

`complete_through`, returned on every feed page, is the time up to which every change has been published. When a page has `has_more: false`, you have everything published before that time.

## Bursts

Most days a register changes a little. Some events change a lot of records at once, and your integration should handle them without alarms or manual work:

| Event | What you see | How big |
| - | - | - |
| **Register reload.** A register is rebuilt from its source, for example after the office reissues its data. | Every record of the register is published again, with a new `updated_at`, usually with no visible change. | The whole register. The Chinese register has about 95 million records. |
| **Processing change.** Pinakel improves how source data is mapped or normalized. | Records processed after the change are published again, some with changed values such as `name_key`. | Up to every record in the affected registers, spread over the following update runs. |
| **Normal churn in large registers.** | Many records change every day. The United States register changes daily in large numbers. | Thousands to hundreds of thousands per day. |

Large republishes are spread over several update runs, so a burst can last hours or days.

To absorb bursts:

* upsert by `id`, so a repeated record overwrites itself;
* compare the fields you care about with your stored copy before raising a docket event or an alert, and ignore changes to `updated_at` alone;
* process feed pages in a queue rather than in the request path of your own users;
* keep following the cursor; there is nothing to reset after a burst.

## Reloads

While a register is reloading:

* its `state` in [`GET /v1/jurisdictions`](https://docs.pinakelai.com/api-reference/jurisdictions/list) is `reloading`;
* searches skip it and list it in `unavailable_jurisdictions`;
* retrieving one of its records gets 503 [`jurisdiction-unavailable`](https://docs.pinakelai.com/errors/jurisdiction-unavailable), with `Retry-After` of at least 900 seconds, and batch requests list its ids under `unavailable`;
* a feed request naming only reloading registers gets the same 503; a wider feed request lists them in `unavailable_jurisdictions` and continues with the others.

Your stored feed cursor stays valid. When the reload finishes, the register's changes, including the republished records, flow through the feed in order.

## Removals

In v1, records the office removes are not announced in the feed. The type `trademark.removed` is reserved for this and will be added in a later version; ignore change types you do not know.

Until then, verify the records you depend on from time to time: a [batch retrieve](https://docs.pinakelai.com/api-reference/trademarks/batch.md) of your ids lists missing ones under `not_found`.

## Not a history

The API serves the current state of each record. It does not keep earlier versions, and the feed is not an event log of the office: if a record changes twice between your polls, the feed item carries the latest state. If you need history, store the versions you receive.


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