Skip to main content

Request history

Request history lets your server look up what Thumbmark returned for an identification, instead of trusting what the browser reports. It also lets you delete a visitor's stored request records and visitor entries. Some copies expire on their own schedule, see Data handling.

Availability

Request history is not a console setting. It is enabled per account by Thumbmark on request. Contact Thumbmark to enable it for your account. Until it is enabled, the request-history permissions are not offered when you create a secret.

All calls on this page need a management secret with the right scope. Console sign-in tokens are not accepted. Keep the secret on your server, see Store a secret safely.

Scopes and who can create the secret​

Console labelScopeAllows
Read request historyrequests:readGET /v1/requests/{requestId} and GET /v1/requests
Delete visitor datavisitors:deleteDELETE /v1/visitors/{visitorId}

Only an account admin can create a secret with these scopes, and only on an account where request history is enabled. In the console, select them under Permissions in the Create Management Secret dialog, see Create a management secret. A secret that carries a request-history scope is hidden from team members who are not account admins. If an admin who created request-history secrets is demoted to member or removed from the account, those secrets are revoked.

A secret can carry several scopes, but we recommend creating a separate secret for reading and for deleting (least privilege). The active secret limit applies to these secrets as well.

A secret is accepted on a request-history route only if it carries the matching scope. A missing, invalid or revoked secret, a missing scope and a console token are all answered by 403 with {"message":"Forbidden"}, see Troubleshooting 403. If the secret is accepted but request history is off for your account, the answer is 403 with the error code REQUEST_HISTORY_NOT_ENABLED instead.

Requests to these routes can also be answered with 429 Too Many Requests ({"message":"Too Many Requests"}) when you send too many. Wait and retry later. A 503 means that request history cannot be served right now, so retry with backoff.

Get a request​

GET /v1/requests/{requestId} returns what Thumbmark returned for one identification. The requestId is the one in the identification response, and may contain letters, digits and the characters . _ ~ = -, up to 128 characters.

curl -sS https://admin-api.thumbmarkjs.com/v1/requests/$REQUEST_ID \
-H "Authorization: Bearer $THUMBMARK_MANAGEMENT_SECRET"

The response is the identification response as computed at the time, without the internal collect field. components merges the server-side and browser-side components into one object. Two fields are added:

  • requestedAt: when the request was made.
  • componentsComplete: true when the browser-side components were joined into components. If it is false, components holds the server-side components only.

Statuses:

StatusMeaning
200The stored request.
400The requestId is malformed.
404Error code REQUEST_NOT_FOUND. The id never existed, has expired, belongs to another account, or is still being written.
403See above: the secret is rejected, or request history is not enabled.

A record can take a few seconds to appear. If the request was made less than 30 seconds ago, retry with backoff for up to 30 seconds before you treat the id as unknown.

List a visitor's requests​

GET /v1/requests returns the requests of one visitor, newest first, in the same shape as the response above.

curl -sS "https://admin-api.thumbmarkjs.com/v1/requests?visitorId=$VISITOR_ID&limit=20" \
-H "Authorization: Bearer $THUMBMARK_MANAGEMENT_SECRET"
ParameterDescription
visitorIdRequired. Letters, digits and the characters . _ ~ -, up to 128 characters.
from, toOptional, both inclusive. An RFC 3339 UTC instant such as 2026-10-26T12:00:00Z, or a date such as 2026-10-01, which stands for the whole UTC day. They default to your retention window and are clamped to it.
limitOptional page size from 1 to 50. The default is 20. A larger value is a 400.
cursorOptional. The nextCursor of the previous page.

The response is {"items":[...]}, plus nextCursor while more pages remain. Keep following nextCursor until it is absent. A page can contain fewer items than limit, or none at all, and still have a nextCursor, so only a missing nextCursor means that you are done. An unknown visitor, a visitor without records in the window, and a visitor of another account all return {"items":[]}.

Delete a visitor​

DELETE /v1/visitors/{visitorId} deletes the visitor's stored request records, including any stored IP address, and the visitor entries for your account. Some copies age out on their own schedule, see Data handling.

curl -sS -i -X DELETE https://admin-api.thumbmarkjs.com/v1/visitors/$VISITOR_ID \
-H "Authorization: Bearer $THUMBMARK_MANAGEMENT_SECRET"
StatusMeaning
204The visitor's request records and visitor entries are deleted. Some copies age out on their own schedule, see Data handling. Also returned when nothing existed, and for the visitor id of another account, which deletes nothing.
202The deletion is not finished. The body is {"status":"in_progress","deleted":{...}} with the counts deleted so far, and the Retry-After header says how many seconds to wait.

When you get 202, wait for Retry-After seconds and repeat the same call until you receive 204. A 202 is not a success: records and visitor entries are only confirmed deleted once you get 204. The call keeps working after request history has been switched off for your account. Because the call is repeatable, you can safely run it again if your own process was interrupted.

A later identification of the same browser creates a new visitor.

Use request history from the SDK​

The Node.js SDK wraps these routes. It needs a secret with the matching scope, and an account with request history enabled.

MethodRoute
client.requests.get(requestId)GET /v1/requests/{requestId}
client.requests.list({ visitorId, from, to, limit, cursor })GET /v1/requests
client.requests.listAll({ visitorId, from, to, limit })GET /v1/requests, repeated for every page
client.visitors.delete(visitorId, { maxAttempts })DELETE /v1/visitors/{visitorId}

get returns the record. A 404 is never retried by the SDK, so if the request was made seconds ago, retry yourself:

get-request.mjs
import { createManagementClient, NotFoundError } from '@thumbmarkjs/management';

const client = createManagementClient({
apiKey: process.env.THUMBMARK_MANAGEMENT_SECRET,
});

const requestId = process.argv[2];

// A record can take a few seconds to appear. Retry a "not found" for up to 30 seconds.
const deadline = Date.now() + 30_000;
let delayMs = 500;
let record;
while (record === undefined) {
try {
record = await client.requests.get(requestId);
} catch (err) {
if (!(err instanceof NotFoundError) || Date.now() + delayMs > deadline) throw err;
await new Promise((resolve) => setTimeout(resolve, delayMs));
delayMs = Math.min(delayMs * 2, 5_000);
}
}
console.log(record.requestId, record.requestedAt, 'complete:', record.componentsComplete);

list returns one page as { items, nextCursor }. listAll is an async iterable that follows nextCursor for you until it is absent:

list-requests.mjs
import { createManagementClient } from '@thumbmarkjs/management';

const client = createManagementClient({
apiKey: process.env.THUMBMARK_MANAGEMENT_SECRET,
});

const visitorId = process.argv[2];

for await (const record of client.requests.listAll({ visitorId, from: '2026-10-01' })) {
console.log(record.requestId, record.requestedAt);
}

visitors.delete repeats the DELETE call for you. It waits for the Retry-After of each 202 response (2 seconds if there is none, and never more than 10 seconds), and it resolves only when the API answers 204. After maxAttempts attempts (the default is 10) without a 204, it throws a VisitorDeletionIncompleteError. Each HTTP call uses a timeout of at least 25 seconds, because a single call can take a while.

delete-visitor.mjs
import {
createManagementClient,
VisitorDeletionIncompleteError,
} from '@thumbmarkjs/management';

const client = createManagementClient({
apiKey: process.env.THUMBMARK_MANAGEMENT_SECRET,
});

const visitorId = process.argv[2];

try {
await client.visitors.delete(visitorId);
console.log(`${visitorId}: deletion confirmed`);
} catch (err) {
if (err instanceof VisitorDeletionIncompleteError) {
// Not finished. Calling delete() again resumes it.
console.error(`${visitorId}: not finished yet, retry after ${err.retryAfterSeconds} s`, err.deleted);
process.exitCode = 1;
} else {
throw err;
}
}

Errors​

  • RequestHistoryNotEnabledError: the API accepted the secret, but request history is not enabled for your account (403 with code REQUEST_HISTORY_NOT_ENABLED). Rotating the secret will not help. Contact Thumbmark.
  • AuthenticationError: the API rejected the secret itself. It does not say whether the secret is missing, invalid, revoked or lacks the scope. See Troubleshooting 403.
  • NotFoundError (get only): the request was not found, see Get a request.
  • ValidationError: an invalid visitorId, requestId, limit, date or cursor.
  • VisitorDeletionIncompleteError: the deletion was not confirmed. Its status is 202 even though it is thrown, so do not treat it as success. It has deleted (the progress reported by the last 202) and retryAfterSeconds. Call visitors.delete() again to resume. Repeating the call is safe.
  • A 429 is reported as a plain ManagementApiError and is not retried by the SDK. See Errors and handle it in your own code.

Data handling​

You, as the controller of your end-users' data, decide when to read or delete records, for example when handling a data-subject request. Thumbmark processes this data on your behalf under your data processing agreement. Deletion works per visitorId, so you need to identify every visitor id that belongs to the person yourself. This page describes how the API behaves and is not legal advice.

  • Records are kept for your account's retention period, which is 90 days by default and can be shorter, but not longer. An expired record is not returned.
  • The raw IP address is returned only if it was stored under your data processing agreement and the account setting for it is currently on. The stored ip_identifier is pseudonymous, not anonymous.
  • Stored request records are pseudonymous personal data, not anonymized.
  • metadata is content you send. Do not put personal data in it; if you do, it is removed with the request record.
  • Deleting a visitor removes the visitor's request records and visitor entries. Other copies are not removed at once and expire on their own:
    • Shared component data, log and export copies, and usage aggregates expire within 120 days at most (retention plus 30 days, with a retention of 90 days at most).
    • Backups clear within 7 days.
    • Logs and queues clear within 14 days.

Next steps​