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.
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 label | Scope | Allows |
|---|---|---|
| Read request history | requests:read | GET /v1/requests/{requestId} and GET /v1/requests |
| Delete visitor data | visitors:delete | DELETE /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:truewhen the browser-side components were joined intocomponents. If it isfalse,componentsholds the server-side components only.
Statuses:
| Status | Meaning |
|---|---|
200 | The stored request. |
400 | The requestId is malformed. |
404 | Error code REQUEST_NOT_FOUND. The id never existed, has expired, belongs to another account, or is still being written. |
403 | See 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"
| Parameter | Description |
|---|---|
visitorId | Required. Letters, digits and the characters . _ ~ -, up to 128 characters. |
from, to | Optional, 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. |
limit | Optional page size from 1 to 50. The default is 20. A larger value is a 400. |
cursor | Optional. 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"
| Status | Meaning |
|---|---|
204 | The 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. |
202 | The 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.
| Method | Route |
|---|---|
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:
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:
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.
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 (403with codeREQUEST_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(getonly): the request was not found, see Get a request.ValidationError: an invalidvisitorId,requestId,limit, date or cursor.VisitorDeletionIncompleteError: the deletion was not confirmed. Itsstatusis202even though it is thrown, so do not treat it as success. It hasdeleted(the progress reported by the last202) andretryAfterSeconds. Callvisitors.delete()again to resume. Repeating the call is safe.- A
429is reported as a plainManagementApiErrorand 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_identifieris pseudonymous, not anonymous. - Stored request records are pseudonymous personal data, not anonymized.
metadatais 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
- Management secrets: create a secret with the request-history permissions.
- Node.js SDK: configuration, retries and the full list of errors.