--- title: "Unlock events as of a date" method: GET path: "/v5/point-in-time/unlock/events/{tokenId}" tags: ["Point-in-Time History"] --- # Unlock events as of a date `GET /v5/point-in-time/unlock/events/{tokenId}` ## Request - Base URL: `https://api.tokenomist.ai` - URL: `https://api.tokenomist.ai/v5/point-in-time/unlock/events/{tokenId}` - Auth: API key in header `x-api-key` Cliff unlock events as they were known at `asOf`. ## Path parameters - `tokenId` string, required ## Query parameters - `asOf` string - `versionId` string - `start` string, date - `end` string, date - `standardAllocation` string - `page` integer - `pageSize` integer ## Response `200` Successful response - object - `metadata` HistoryPaginatedMetadata - `queryDate` string, date-time: Timestamp of the query - `asOf` string, date-time: The instant the response is evaluated at - `version` HistoryAppliedVersion: The project version that answered the request - `id` string: Permanent version id: `{tokenId}-p-{id}`. The prefix is Tokenomist's own token id, usually the path `tokenId` (not for every token, for example `galxe` versions start with `project-galaxy`). Store it as returned. - `historyOrder` integer: Position on the project timeline (1 = oldest). It can shift when an earlier version is added later, so use `id` as the key. - `validFrom` string, date-time: When the version came into force: its announcement date, else its first publish on Tokenomist - `validFromBasis` 'stated_in_document' | 'onchain' | 'url' | 'archive_first_seen' | 'first_published': How a project version's start date was established. `stated_in_document`: the vote or announcement states the time. `onchain`: a governance proposal's voting end on chain. `url`: the time encoded in the announcement's link. `archive_first_seen`: the first web archive capture (an upper bound). `first_published`: no dated announcement, so the start is the first publish on Tokenomist (public no later than then). - `validUntil` string, date-time, nullable: The next project version's start. Null for the latest version. It can be before `validFrom` when the next version's announcement is dated earlier. - `previousVersionId` string, nullable: The previous project version. Null for the first. - `status` 'current' | 'previous': Relative to now, not asOf: current for the latest project version of a token that is live today, else previous. An asOf that selects a since-replaced version gets previous. - `credit` Credit: Optional quota state for the calling account, returned on most authenticated responses (both success and error). Treat it as optional: it may be absent on unauthenticated requests, demo/playground responses, and briefly right after a monthly reset. `used` is near-real-time and may lag the true count by a request or two. - `used` integer: Successful requests (status below 400) made by your account, across all its keys, since the start of the month; errors use no credit. May lag by a request or two. - `limit` integer: The plan's request quota for the window. - `resetAt` string, date-time: When the quota resets: the 1st of next month, 00:00 UTC (RFC 3339). - `page` integer: Current page number (1-indexed) - `pageSize` integer: Number of items per page - `totalPages` integer: Total number of pages available for the current query - `total` integer: Total number of items across all pages - `status` boolean - `data` HistoryUnlockEvent[] - `unlockDate` string, date-time: Unlock time. One entry per instant: the allocations unlocking at the same second are grouped. - `tokenName` string: Token name - `tokenSymbol` string: Token symbol - `listedMethod` 'INTERNAL' | 'AI' | 'EXTERNAL' | '': How the data was listed: INTERNAL (Tokenomist research from official sources or on-chain data), AI (AI-listed) or EXTERNAL (submitted by the project). Empty for an unknown listing type. - `dataSource` string: Where the schedule comes from: Whitepaper, Onchain, AI-Listing, Self-Listed or TokenUnlocks. - `cliffUnlocks` object: The cliff unlock at this time, as known in the selected version (no USD fields). - `cliffAmount` number: Total unlock amount denominated in token - `allocationBreakdown` HistoryCliffAllocationBreakdown[]: One row per allocation unlocking at this time. - `unlockDate` string, date-time: Unlock time (the same instant as the event's unlockDate). - `allocationName` string: Allocation name - `standardAllocationName` string: One of Founder / Team, Private Investors, Public Investors, Community, Others or Reserve (filter keys founderTeam, privateInvestors, publicInvestors, community, others, reserve). Empty when the allocation has no standard category. - `cliffAmount` number: Unlock amount denominated in token - `unlockPrecision` string: Precision of the unlock date, for example second, hour, day, month - `committedClaim` HistoryClaim, nullable: Committed claim as of asOf, without its USD value. Null when there is no claim, it has no timestamp, or it was made after asOf. A day's claim sums only its allocations' claims made by asOf. - `amount` number, nullable: Committed claim amount denominated in token - `timestamp` integer, nullable: Unix time in seconds of the claim (the latest when several are merged). ## Other responses - `400`: Error. `400 INVALID_AS_OF`: `asOf` is invalid or in the future. `400 INVALID_PARAMETER`: another parameter is invalid. `403 PLAN_NOT_ELIGIBLE`: your plan does not include the version selector on this endpoint, or `asOf` / `versionId` is outside your plan's range (a 403 without `errorCode` means your plan does not include the endpoint). `404 TOKEN_NOT_FOUND`, `404 NO_VERSION_AT_AS_OF` (no project version in force at `asOf`), `404 VERSION_NOT_FOUND` (`versionId` does not belong to this token). `422 INVALID_PARAMETER`: `asOf` and `versionId` together, or `start` / `end` outside your plan's window. `429` (no `errorCode`): rate limit or monthly credit quota, as in v5. `503 SERVICE_UNAVAILABLE`: retry shortly. Errors use no credit. - `403`: Error. `400 INVALID_AS_OF`: `asOf` is invalid or in the future. `400 INVALID_PARAMETER`: another parameter is invalid. `403 PLAN_NOT_ELIGIBLE`: your plan does not include the version selector on this endpoint, or `asOf` / `versionId` is outside your plan's range (a 403 without `errorCode` means your plan does not include the endpoint). `404 TOKEN_NOT_FOUND`, `404 NO_VERSION_AT_AS_OF` (no project version in force at `asOf`), `404 VERSION_NOT_FOUND` (`versionId` does not belong to this token). `422 INVALID_PARAMETER`: `asOf` and `versionId` together, or `start` / `end` outside your plan's window. `429` (no `errorCode`): rate limit or monthly credit quota, as in v5. `503 SERVICE_UNAVAILABLE`: retry shortly. Errors use no credit. - `404`: Error. `400 INVALID_AS_OF`: `asOf` is invalid or in the future. `400 INVALID_PARAMETER`: another parameter is invalid. `403 PLAN_NOT_ELIGIBLE`: your plan does not include the version selector on this endpoint, or `asOf` / `versionId` is outside your plan's range (a 403 without `errorCode` means your plan does not include the endpoint). `404 TOKEN_NOT_FOUND`, `404 NO_VERSION_AT_AS_OF` (no project version in force at `asOf`), `404 VERSION_NOT_FOUND` (`versionId` does not belong to this token). `422 INVALID_PARAMETER`: `asOf` and `versionId` together, or `start` / `end` outside your plan's window. `429` (no `errorCode`): rate limit or monthly credit quota, as in v5. `503 SERVICE_UNAVAILABLE`: retry shortly. Errors use no credit. - `422`: Error. `400 INVALID_AS_OF`: `asOf` is invalid or in the future. `400 INVALID_PARAMETER`: another parameter is invalid. `403 PLAN_NOT_ELIGIBLE`: your plan does not include the version selector on this endpoint, or `asOf` / `versionId` is outside your plan's range (a 403 without `errorCode` means your plan does not include the endpoint). `404 TOKEN_NOT_FOUND`, `404 NO_VERSION_AT_AS_OF` (no project version in force at `asOf`), `404 VERSION_NOT_FOUND` (`versionId` does not belong to this token). `422 INVALID_PARAMETER`: `asOf` and `versionId` together, or `start` / `end` outside your plan's window. `429` (no `errorCode`): rate limit or monthly credit quota, as in v5. `503 SERVICE_UNAVAILABLE`: retry shortly. Errors use no credit. - `429`: Error. `400 INVALID_AS_OF`: `asOf` is invalid or in the future. `400 INVALID_PARAMETER`: another parameter is invalid. `403 PLAN_NOT_ELIGIBLE`: your plan does not include the version selector on this endpoint, or `asOf` / `versionId` is outside your plan's range (a 403 without `errorCode` means your plan does not include the endpoint). `404 TOKEN_NOT_FOUND`, `404 NO_VERSION_AT_AS_OF` (no project version in force at `asOf`), `404 VERSION_NOT_FOUND` (`versionId` does not belong to this token). `422 INVALID_PARAMETER`: `asOf` and `versionId` together, or `start` / `end` outside your plan's window. `429` (no `errorCode`): rate limit or monthly credit quota, as in v5. `503 SERVICE_UNAVAILABLE`: retry shortly. Errors use no credit. - `503`: Error. `400 INVALID_AS_OF`: `asOf` is invalid or in the future. `400 INVALID_PARAMETER`: another parameter is invalid. `403 PLAN_NOT_ELIGIBLE`: your plan does not include the version selector on this endpoint, or `asOf` / `versionId` is outside your plan's range (a 403 without `errorCode` means your plan does not include the endpoint). `404 TOKEN_NOT_FOUND`, `404 NO_VERSION_AT_AS_OF` (no project version in force at `asOf`), `404 VERSION_NOT_FOUND` (`versionId` does not belong to this token). `422 INVALID_PARAMETER`: `asOf` and `versionId` together, or `start` / `end` outside your plan's window. `429` (no `errorCode`): rate limit or monthly credit quota, as in v5. `503 SERVICE_UNAVAILABLE`: retry shortly. Errors use no credit. ## Changes - **2026-11-03** `37c15ea7bdbd`: 1 info - endpoint added [Operation history](https://skmtc.dev/tokenomist/apis/tokenomist-api/changes/v5/point-in-time/unlock/events/:tokenId/get.md) --- [API](https://skmtc.dev/tokenomist/apis/tokenomist-api.md) - [All operations](https://skmtc.dev/tokenomist/apis/tokenomist-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tokenomist/apis/tokenomist-api/revisions/37c15ea7bdbd?raw)