---
title: "Unlock Events List v5"
method: GET
path: "/v5/unlock/events/list"
tags: ["Unlock Events"]
---

# Unlock Events List v5

`GET /v5/unlock/events/list`

## Request

- Base URL: `https://api.tokenomist.ai`
- URL: `https://api.tokenomist.ai/v5/unlock/events/list`
- Auth: API key in header `x-api-key`

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.

## Query parameters

- `minUnlockDate` string, date
- `maxUnlockDate` string, date
- `minMarketCap` number
- `minReleasedPercentage` number
- `minTotalUnlockAmount` number
- `minValueToMarketCap` number
- `standardAllocation` string
- `page` integer
- `pageSize` integer

## Response `200`

Successful response

- object
  - `metadata` PaginatedMetadata
    - `queryDate` string, date-time: Timestamp of the query
    - `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-based). 1 on an empty result.
    - `pageSize` integer: Rows per page (20 by default).
    - `totalPages` integer: Number of pages for this query (1 on an empty result).
    - `total` integer: Number of rows across all pages. Left out when the result is empty.
  - `status` boolean
  - `data` UnlockEventListV5Item[]
    - `tokenId` string: Token slug
    - `tokenName` string: Token name
    - `tokenSymbol` string: Token symbol
    - `marketCap` number, nullable: Current market cap in USD. Null when unknown.
    - `releasedPercentage` number: 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.
    - `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.
    - `events` object[]: The token's cliff unlocks in the date range, oldest first.
      - `unlockDate` string, date-time: Unlock time. One entry per instant: the allocations unlocking at the same second are grouped.
      - `referencePrice` number: 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.
      - `referencePriceUpdatedTime` string, date-time: 00:00 UTC of the day whose close is referencePrice; equals unlockDate when the current price is used.
      - `cliffUnlocks` UpcomingCliffUnlocksV5: Cliff unlock of an event on the upcoming and list endpoints. Its fields differ from CliffUnlocksV5 (totalCliffAmount, totalCliffValue; a shorter breakdown).
        - `totalCliffAmount` number: Tokens unlocking at this instant, summed over the breakdown (after the standardAllocation filter)
        - `totalCliffValue` number: totalCliffAmount × referencePrice, in USD
        - `valueToMarketCap` number, nullable: totalCliffValue ÷ the token's current market cap × 100 (percent). Null when the market cap is unknown.
        - `allocationBreakdown` UpcomingCliffAllocationBreakdownV5[]: One row per allocation unlocking at this time.
          - `allocationName` string: Allocation name
          - `standardAllocationName` string: One of Founder / Team, Private Investors, Public Investors, Community, Others or Reserve. Empty when the allocation has no standard category.
          - `cliffAmount` number: Tokens this allocation unlocks at the event
          - `cliffValue` number: cliffAmount × referencePrice, in USD
          - `unlockPrecision` string: How precisely the unlock time is known (second, day, month, ...); empty when not recorded
      - `latestUpdateDate` string, date-time: When this unlock's schedule was last updated in Tokenomist's data.

## Other responses

- `400`: 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.
- `401`: 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.
- `403`: 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.
- `422`: 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.
- `429`: 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.
- `500`: 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.
- `503`: 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.

## Changes

- **2026-11-03** `37c15ea7bdbd`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tokenomist/apis/tokenomist-api/changes/v5/unlock/events/list/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)