--- title: "Allocations as of a date" method: GET path: "/v5/point-in-time/allocations/{tokenId}" tags: ["Point-in-Time History"] --- # Allocations as of a date `GET /v5/point-in-time/allocations/{tokenId}` ## Request - Base URL: `https://api.tokenomist.ai` - URL: `https://api.tokenomist.ai/v5/point-in-time/allocations/{tokenId}` - Auth: API key in header `x-api-key` The allocation table as it was known at `asOf`, with unlocked and locked amounts evaluated at `asOf`. Same shape as Allocations v5 without lastUpdatedDate, plus the applied version. ## Path parameters - `tokenId` string, required ## Query parameters - `asOf` string - `versionId` string ## Response `200` Successful response - object - `metadata` HistoryMetadata - `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). - `status` boolean - `data` object - `name` string: Token name - `symbol` 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). Left out when unknown. - `maxSupply` number, nullable: The token's max supply today, as in v5. Not versioned yet, so a past `asOf` gets today's value. - `totalUnlockedAmount` number: Linear releases up to 00:00 UTC on asOf's day plus all cliffs dated that day; asOf's time of day is ignored. - `totalLockedAmount` number: Sum of the scheduled allocations' locked amounts at `asOf` - `totalUntrackedAmount` number: Today's figure for the selected version, not evaluated at asOf (like maxSupply). - `totalTBDLockedAmount` number: Today's figure for the selected version, not evaluated at asOf (like maxSupply). - `allocations` Allocation[]: Each allocation's unlocked and locked amounts are evaluated at the UTC day of `asOf` - `allocationName` string: Allocation name - `allocationType` 'Scheduled' | 'TBD': Scheduled (a release schedule) or TBD (no schedule yet). An allocation with both parts has one row of each, with the same allocationName. - `standardAllocationName` string: One of Founder / Team, Private Investors, Public Investors, Community, Others or Reserve (filter keys founderTeam, privateInvestors, publicInvestors, community, others, reserve). - `allocationUnlockedAmount` number: Unlocked tokens: linear releases up to 00:00 UTC today plus the cliffs dated today (point-in-time: asOf's UTC day). Always 0 on TBD rows. Can exceed allocationAmount when released TBD supply of the same name is counted here. - `allocationLockedAmount` number: Current locked amount of the allocation, `allocationAmount` minus `allocationUnlockedAmount`, never below 0 - `allocationAmount` number: Tokens in this row: the scheduled part (Scheduled) or the unscheduled part (TBD). - `trackedAllocationPercentage` number, nullable: This row's share of the token's tracked supply, in percent (0-100): allocationAmount ÷ the sum of all rows' allocationAmount × 100. Null when 0. ## 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/allocations/: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)