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. One account only receives OTHER people's email addresses in the clear: an administrator of the brand that issued that product. An administrator of another brand receives the anonymized projection, exactly like a visitor. A SealTrust superadmin receives the clear on every product, because that is the operations account.

The same accounts, and only those, receive 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

600 calls per 60 second window, counted per calling IP address. The window is fixed. The limit is wide because hundreds of visitors at a trade fair or on a mobile network often share one address.

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

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, which describe this limit. Going over returns 429, with these three headers and a Retry-After in seconds.

#Path and query parameters

A single query parameter, lang, and it is optional. It changes one thing in the response: the language of category_name. Everything else is identical whatever its value.

The server picks the language in this order: the lang parameter when it is fr or en, otherwise the first recognised tag of the Accept-Language header, otherwise en. A value the server does not recognise is ignored without an error: you get en, and not a 422.

#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_live_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",
  "serial": "H897RFWJ4972",
  "product_name": "Model 1 bag",
  "brand_id": 42,
  "brand_code": "7K3QXW9M2A",
  "brand_name": "Exemple SAS",
  "brand_hide_powered_by": false,
  "brand_app_url": null,
  "category_id": 7,
  "category_name": "Maroquinerie",
  "metadata_uri": "ipfs://example-de-contenu-non-reel",
  "image_url": "https://example-sas.test/images/sac-modele-1.jpg",
  "current_owner_email": null,
  "current_owner_is_vault": true,
  "identity_included": true,
  "timeline": [
    {
      "type": "verify",
      "token_id": "7719472615821079694904732333912527190217998977709370935963838933860875309329",
      "uid_hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
      "contract_address": "0x2222222222222222222222222222222222222222",
      "timestamp": "2026-08-18T14:02:11.482000Z",
      "signature": "signature-example",
      "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",
      "from_role": "mint",
      "to_role": "vault",
      "comment": "Factory mint",
      "event_id": null
    }
  ],
  "contract_address": "0x2222222222222222222222222222222222222222"
}

The response counts fifteen 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 twenty-two 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.