GETMethod GET/timeline/{identifier}

You read the history of a single product. By the end of this page, you will know how to retrieve the list of its verifications and its changes of ownership, sorted from the most recent to the oldest, along with the record of the product this history belongs to.

Full address:

GET https://api.sealtrust.io/v1/timeline/{identifier}

The same endpoint also answers without the /v1 prefix, at https://api.sealtrust.io/timeline/{identifier}. Both addresses call the same code. Use the /v1 form for a new integration.

#Authorization

None. This endpoint is public.

You do not need an API key. If you send one in the Authorization header, we decode it as a console session token. An API key is not a session token: the read fails silently, and we treat the call as an anonymous call. You therefore receive the same response with or without an API key.

A console session token, on the other hand, changes the response. We read it from the Authorization header as well as from the session cookie set by the console. The brand administrator and the product's current owner then receive the email addresses in the clear. The administrator additionally receives the wallet addresses in from_address and to_address.

On an anonymous call, you receive an anonymized projection:

• we do not return the wallet addresses, from_address and to_address equal null;
• we mask the email addresses: the value returned keeps the first two characters of the local part, then ..., then six stable characters, for example ma...3f9c1d.

#Rate limit

30 calls per 60 second window, counted per calling IP address. The window is fixed.

Calls on /v1/timeline/… and on /timeline/… feed the same counter. Switching from one form to the other therefore does not raise the limit.

Going over returns 429, with a body that restates the limit. That response carries no Retry-After. It does carry x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset, whose values do not describe this endpoint's limit.

The 200 responses carry these same three headers, with the same values. Do not use these headers here to set your pace. On a 429, wait for the end of the current window, that is, at most 60 seconds.

#Path and query parameters

This endpoint has no query parameter.

#The three accepted forms of identifier

This parameter accepts three forms. You send the one you have at hand.

We recognize the serial number whatever the case. We read the characters I and L as a 1, and the character O as a 0, in order to accept a number copied by hand from a label. We do not recover the U: it belongs neither to the alphabet of serial numbers nor to the translated characters, and an identifier that contains one designates no product.

#Headers

No header is required.

#Request body

None. This request has no body.

#Example request

Reading the history of the product whose printed number is EXEMP1E00001.

curl -i https://api.sealtrust.io/v1/timeline/EXEMP1E00001

import { SealTrustClient } from "@sealtrust-io/sdk";

// This endpoint is public and ignores the key, but the SDK client
// refuses to be constructed without it.
const sealtrust = new SealTrustClient({
  apiKey: "st_test_0000000000000000000000000000000000000000000000",
});

const historique = await sealtrust.verify.timeline("EXEMP1E00001");

console.log(historique.product_name, historique.timeline.length);

import requests

response = requests.get(
    "https://api.sealtrust.io/v1/timeline/EXEMP1E00001",
    timeout=30,
)

print(response.status_code)
print(response.json())

#Example response

HTTP code 200.

This product has been minted, it has not been claimed by a customer yet, and it has been scanned once by QR.

{
  "token_id": "7719472615821079694904732333912527190217998977709370935963838933860875309329",
  "product_name": "Sac modèle 1",
  "brand_id": 42,
  "brand_name": "Exemple SAS",
  "category_id": null,
  "category_name": "Maroquinerie",
  "metadata_uri": "ipfs://exemple-de-contenu-non-reel",
  "image_url": "https://exemple-sas.test/images/sac-modele-1.jpg",
  "current_owner_email": null,
  "current_owner_is_vault": true,
  "timeline": [
    {
      "type": "verify",
      "token_id": "7719472615821079694904732333912527190217998977709370935963838933860875309329",
      "uid_hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
      "contract_address": "0x2222222222222222222222222222222222222222",
      "timestamp": "2026-08-18T14:02:11.482000Z",
      "signature": "signature-exemple",
      "is_valid": true,
      "source": "qr",
      "from_address": null,
      "to_address": null,
      "from_email": null,
      "to_email": null,
      "from_display": null,
      "to_display": null,
      "comment": "Scanned",
      "event_id": null
    },
    {
      "type": "transfer",
      "token_id": "7719472615821079694904732333912527190217998977709370935963838933860875309329",
      "uid_hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
      "contract_address": "0x2222222222222222222222222222222222222222",
      "timestamp": "2026-08-12T09:30:00.000000Z",
      "signature": null,
      "is_valid": null,
      "source": null,
      "from_address": null,
      "to_address": null,
      "from_email": "Mint",
      "to_email": null,
      "from_display": "Mint",
      "to_display": "Vault",
      "comment": "Factory mint",
      "event_id": null
    }
  ],
  "contract_address": "0x2222222222222222222222222222222222222222"
}

The response counts twelve fields and nothing else. You receive null for the fields without a value, they do not disappear from the response.

The timeline array is not paginated and has no maximum size. It contains every verification and every movement recorded for this product. A heavily scanned product therefore returns a large response. Size your read accordingly.

#An event of the timeline

Each entry counts sixteen fields. The fields that have no meaning for the type of event equal null.

#Errors

The body of an error response carries a detail field.

#See also

• GET /resolve/{identifier}, read in one call everything a product page displays.
• GET /products/{uid}/public, read the public information of a product.
• GET /p/{serial}, translate the printed serial number into a consumer page address.
• Core concepts, tell model, batch and item apart before ordering a single label.