> ## Documentation Index > Fetch the complete documentation index at: https://docs.tokenomist.ai/llms.txt > Use this file to discover all available pages before exploring further. # Unlock Events List API v5 > Cliff unlock events of every token in a date range Cliff unlock events of every token between `minUnlockDate` and `maxUnlockDate`, grouped by token and sorted by `tokenId`. Both dates default to your plan's window, counted from today. Use the filters to keep large or high-impact unlocks only. For one token's events, use [Unlock Events v5](https://docs.tokenomist.ai/api-documents/unlock-events/v5.md). ## OpenAPI ````yaml GET /v5/unlock/events/list openapi: 3.0.3 info: title: Tokenomist API description: >- Comprehensive time series data for crypto token unlocks, emissions, allocations, fundraising, burns, and buybacks. version: 1.0.0 servers: - url: https://api.tokenomist.ai security: - apiKey: [] paths: /v5/unlock/events/list: get: tags: - Unlock Events summary: Unlock Events List v5 description: >- Cliff unlock events of every token in a date range, grouped by token and sorted by tokenId. Cliff unlocks only. A token whose events are all filtered out is left out. Free trial: only the 50 trial tokens. operationId: getUnlockEventListV5 parameters: - name: minUnlockDate in: query required: false description: >- Earliest unlock date (YYYY-MM-DD). Defaults to the start of your plan's window (today minus its years back). Outside the window: 422 "unlock date must be within the allowed range: A to B". schema: type: string format: date - name: maxUnlockDate in: query required: false description: >- Latest unlock date (YYYY-MM-DD) = 00:00 UTC that day: an unlock at exactly 00:00 is included, a later one that day is not. Defaults to the end of your plan's window (today plus its years ahead). Outside the window, or before minUnlockDate: 422. schema: type: string format: date - name: minMarketCap in: query required: false description: >- Minimum current market cap, in USD. When set, tokens without a market cap are left out. schema: type: number - name: minReleasedPercentage in: query required: false description: Minimum releasedPercentage of the token, in percent (0-100). schema: type: number - name: minTotalUnlockAmount in: query required: false description: >- Keep only events whose totalCliffAmount is at least this many tokens (not USD). schema: type: number - name: minValueToMarketCap in: query required: false description: >- Keep only events whose valueToMarketCap is at least this percent (5 means 5%). When set, events without a market cap are left out. schema: type: number - name: standardAllocation in: query required: false description: >- Comma-separated standard allocations to keep. Allowed values: community, founderTeam, privateInvestors, publicInvestors, others, reserve; another value: 422. An event without a matching allocation is dropped; totalCliffAmount and totalCliffValue are recalculated from the kept allocations, valueToMarketCap is not. schema: type: string - $ref: '#/components/parameters/V5Page' - $ref: '#/components/parameters/V5PageSize' responses: '200': description: Successful response content: application/json: schema: type: object properties: metadata: $ref: '#/components/schemas/PaginatedMetadata' status: type: boolean data: type: array items: $ref: '#/components/schemas/UnlockEventListV5Item' '400': $ref: '#/components/responses/V5Error' '401': $ref: '#/components/responses/V5Error' '403': $ref: '#/components/responses/V5Error' '422': $ref: '#/components/responses/V5Error' '429': $ref: '#/components/responses/V5Error' '500': $ref: '#/components/responses/V5Error' '503': $ref: '#/components/responses/V5Error' components: parameters: V5Page: name: page in: query required: false description: >- Page number, 1-based. 0 or omitted: page 1. A page past the last returns the last page again, so stop at `metadata.totalPages`. Negative: 400. schema: type: integer minimum: 0 V5PageSize: name: pageSize in: query required: false description: 'Rows per page. 0 or omitted: 20. No maximum. Negative: 400.' schema: type: integer minimum: 0 schemas: PaginatedMetadata: type: object properties: queryDate: type: string format: date-time description: Timestamp of the query example: '2026-01-08T10:13:58Z' credit: $ref: '#/components/schemas/Credit' page: type: integer description: Current page number (1-based). 1 on an empty result. example: 1 pageSize: type: integer description: Rows per page (20 by default). example: 50 totalPages: type: integer description: Number of pages for this query (1 on an empty result). example: 10 total: type: integer description: Number of rows across all pages. Left out when the result is empty. example: 487 UnlockEventListV5Item: type: object properties: tokenId: type: string description: Token slug example: layerzero tokenName: type: string description: Token name example: LayerZero tokenSymbol: type: string description: Token symbol example: ZRO marketCap: type: number description: Current market cap in USD. Null when unknown. nullable: true example: 278811255 releasedPercentage: type: number description: >- Percent (0-100) of the token's total supply the tracked schedule has unlocked as of the latest refresh (shortly before the request). Not circulating supply. example: 35.28 listedMethod: type: string enum: - INTERNAL - AI - EXTERNAL - '' description: >- 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. example: INTERNAL dataSource: type: string description: >- Where the schedule comes from: Whitepaper, Onchain, AI-Listing, Self-Listed or TokenUnlocks. example: Whitepaper events: type: array description: The token's cliff unlocks in the date range, oldest first. items: type: object properties: unlockDate: type: string description: >- Unlock time. One entry per instant: the allocations unlocking at the same second are grouped. format: date-time example: '2025-11-20T11:00:00Z' referencePrice: type: number description: >- USD price used for the values: the daily close of the unlock's UTC day, or the first later close; the current price when no close exists yet. example: 1.4 referencePriceUpdatedTime: type: string format: date-time description: >- 00:00 UTC of the day whose close is referencePrice; equals unlockDate when the current price is used. example: '2025-11-20T11:00:00Z' cliffUnlocks: $ref: '#/components/schemas/UpcomingCliffUnlocksV5' latestUpdateDate: type: string format: date-time description: >- When this unlock's schedule was last updated in Tokenomist's data. example: '2025-06-13T07:30:52Z' Credit: type: object description: >- 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. properties: used: type: integer description: >- 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. example: 213 limit: type: integer description: The plan's request quota for the window. example: 1000 resetAt: type: string format: date-time description: 'When the quota resets: the 1st of next month, 00:00 UTC (RFC 3339).' example: '2026-08-01T00:00:00Z' UpcomingCliffUnlocksV5: type: object description: >- Cliff unlock of an event on the upcoming and list endpoints. Its fields differ from CliffUnlocksV5 (totalCliffAmount, totalCliffValue; a shorter breakdown). properties: totalCliffAmount: type: number description: >- Tokens unlocking at this instant, summed over the breakdown (after the standardAllocation filter) example: 92645833.3 totalCliffValue: type: number description: totalCliffAmount × referencePrice, in USD example: 129704166.62 valueToMarketCap: type: number nullable: true description: >- totalCliffValue ÷ the token's current market cap × 100 (percent). Null when the market cap is unknown. example: 46.52 allocationBreakdown: type: array description: One row per allocation unlocking at this time. items: $ref: '#/components/schemas/UpcomingCliffAllocationBreakdownV5' V5ErrorBody: type: object properties: metadata: type: object properties: queryDate: type: string format: date-time example: '2026-11-03T09:10:52Z' credit: $ref: '#/components/schemas/Credit' status: type: boolean example: false statusCode: type: integer example: 403 errorMessage: type: string example: This token is not supported data: type: array description: On a 422 validation error, the fields that failed. items: type: object properties: key: type: string value: {} message: type: string UpcomingCliffAllocationBreakdownV5: type: object properties: allocationName: type: string description: Allocation name example: Strategic Partners standardAllocationName: type: string description: >- One of Founder / Team, Private Investors, Public Investors, Community, Others or Reserve. Empty when the allocation has no standard category. example: Private Investors cliffAmount: type: number description: Tokens this allocation unlocks at the event example: 92645833.3 cliffValue: type: number description: cliffAmount × referencePrice, in USD example: 129704166.62 unlockPrecision: type: string description: >- How precisely the unlock time is known (second, day, month, ...); empty when not recorded example: second responses: V5Error: description: >- Error. Body: `status: false`, `statusCode`, `errorMessage`; `data` lists the failing fields on a 422 validation error. Errors use no credit. 400: a malformed parameter (a negative page, or a start/end date that is not YYYY-MM-DD; on the unlock events list, upcoming unlock events and investor list a malformed date is 422). 401: no `x-api-key`. 403: an unknown key or a plan without API access ("You are not authorized to access this resource"); the plan does not include this endpoint ("Forbidden"); the token is unknown or has no data for this dataset ("This token is not supported"); a trial-plan restriction. 404: the resource does not exist (allocations: the token has no standard allocation; investors: unknown `investorId`). 422: a date outside your plan's window, or an invalid filter value. 429: rate limit or monthly credit quota. 500, 503: server error, retry later. content: application/json: schema: $ref: '#/components/schemas/V5ErrorBody' securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Your Tokenomist API key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.