Skip to main content

Endpoints

GET daily AI usage​

This API is available on Enterprise plans. Querying it requires a plan access token, which only organization administrators can create.

The GET /v1/ai_usage/daily endpoint returns per-user, per-day AI credit usage for the plan associated with the calling token. Each row reports the seat-level and plan-level credits a user consumed on a given day for a given editor type.

info

This is a Tier 3 endpoint and requires the org:ai_metering_usage_read scope. This endpoint can only be used with a plan access token.

note

AI usage data is updated periodically and can lag real-time activity by up to 5–6 hours, so recent usage (including the current day) may be incomplete. The API can provide up to one year of usage.

HTTP Endpoint​

GET /v1/ai_usage/daily

Return value

{
  "rows": [
    {
      "plan_id": String,
      "user_id": String,
      "user_email": String,
      "day": String,
      "editor_type": String,
      "seat_credits_sum": Number,
      "plan_credits_sum": Number,
      "workspace_id": String,
      "workspace_name": String,
      "team_id": String,
      "team_name": String,
      "license_group_id": String,
      "license_group_name": String,
      "metering_period_start": String,
      "metering_period_end": String
    },
    ...
  ],
  "next_cursor": String,
  "has_next_page": Boolean
}
Query parametersDescription
start_date
Required
String
The first day to include, inclusive, as a YYYY-MM-DD calendar date (UTC). AI credit usage has only been collected since 2025-12-01, so start_date must be on or after 2025-12-01. It must also be no more than 366 days before the current UTC day. A value outside this window returns a 400.
end_date
Required
String
The last day to include, inclusive, as a YYYY-MM-DD calendar date (UTC). Must be on or after start_date, must be the current UTC day or earlier, and the range may not exceed 366 days.
user_email
String
Restrict the results to a single Figma user, identified by their email address. When omitted, rows for every user in the plan with usage in the range are returned. Note: The user's email is mapped to a user ID, so if the user's email changes no usage data is lost. You must provide the user's current email address for the request.
limit
Numberdefault: 1000
Maximum number of rows to return. Must be between 1 and 1000, inclusive; a value outside this range returns a 400. Defaults to 1000 when unspecified.
cursor
String
An opaque cursor returned from a previous request, used for pagination.
Response fieldsDescription
plan_id
String
The id of the plan the usage belongs to.
user_id
String
The id of the Figma user that consumed the credits.
user_email
String
The email address of the Figma user that consumed the credits.
day
String
The calendar date (UTC) of the aggregated usage, in YYYY-MM-DD format. Days are bucketed by UTC, with boundaries at midnight (00:00:00Z).
editor_type
String

The editor the AI action was associated with, as a string enum. not_applicable when the underlying AI action had no associated file.

  • figma
  • figjam
  • slides
  • sites
  • buzz
  • make
  • not_applicable
seat_credits_sum
Number
The sum of seat-level (per-user-allocated) credits consumed for this day, user, and editor type, in this combination of team, workspace, and billing group.
plan_credits_sum
Number
The sum of plan-level (shared pool) credits consumed for this day, user, and editor type, in this combination of team, workspace, and billing group.
workspace_id
String
The id of the workspace that contains the file the usage happened in, or null when the usage had no associated workspace.
workspace_name
String
The name of the workspace the usage was attributed to, or null when the usage had no associated workspace.
team_id
String
The id of the team that contains the file the usage happened in, or null when the usage had no associated team.
team_name
String
The name of the team the usage was attributed to, or null when the usage had no associated team.
license_group_id
String
The id of the billing group the user belonged to at the time they used AI, or null when the usage had no associated billing group.
license_group_name
String
The name of the billing group the usage was attributed to, or null when the usage had no associated billing group.
metering_period_start
String
The start of the plan-scoped metering period this usage belongs to, as an RFC 3339 UTC timestamp (e.g. 2026-05-01T00:00:00Z).
metering_period_end
String
The end of the plan-scoped metering period this usage belongs to, as an RFC 3339 UTC timestamp (e.g. 2026-06-01T00:00:00Z).
next_cursor
String
An opaque cursor to pass as the cursor query parameter to fetch the next page. Empty when there are no more pages.
has_next_page
Boolean
Whether there is a next page of results to fetch.
Error codesDescription
400A query parameter was missing or malformed (for example, an invalid date, a start_date before 2025-12-01 or more than 366 days in the past, an end_date before the start_date, an end_date in the future, a range longer than 366 days, an out-of-range limit, or an invalid cursor).
401The token is missing, invalid, or the plan is deleted or deactivated.
403The token does not have the org:ai_metering_usage_read scope, or is a resource-restricted plan access token.

Examples​

  • Get all users' daily usage for May 2026:

    curl -H 'X-Figma-Token: <TOKEN>' 'https://api.figma.com/v1/ai_usage/daily?start_date=2026-05-01&end_date=2026-05-31'

  • Get a single user's daily usage for a date range:

    curl -H 'X-Figma-Token: <TOKEN>' 'https://api.figma.com/v1/ai_usage/daily?start_date=2026-05-01&end_date=2026-05-31&user_email=jane@example.com'

Notes on the data​

Keep the following in mind when interpreting the response:

  • Row grain. Usage is aggregated by user × editor_type × day × workspace × team. Because workspace and team are part of the grain, a single user can produce multiple rows for the same day and editor_type (for example, when they used AI in more than one workspace or team that day).
  • Day boundaries are UTC. The day field buckets usage by UTC calendar date, with boundaries at midnight (00:00:00Z).
  • Metering-period boundaries. When two metering periods fall on the same day, all of that day's usage is attributed to the later metering period. As a result, the totals returned here may not exactly match the per-period usage shown in the admin dashboard in Figma.
  • Container names reflect the most recent value. When a workspace, team, or billing group is renamed during a day, that day's rows use the most recent name.
  • Earliest available data. AI credit usage has only been collected since 2025-12-01, so start_date must be on or after this date; an earlier value returns a 400.
  • Field availability. The workspace_id, workspace_name, team_id, team_name, and license_group_name fields have only been populated since 2026-05-29. Rows for earlier days return null for these fields.

Limits​

  • Page size (limit): between 1 and 1000 rows per request, inclusive. Defaults to 1000 when unspecified. A value below 1 or above 1000 returns a 400.
  • Date range: start_date and end_date are UTC YYYY-MM-DD calendar dates. start_date must be on or after 2025-12-01 (when collection began) and no more than 366 days before the current UTC day. end_date must be on or after start_date and no later than the current UTC day. The inclusive range may not exceed 366 days, so you cannot retrieve more than 366 days of data in a single request. Requests that violate any of these constraints return a 400.

Pagination​

The API sorts returned rows by day, then user, then editor_type. The maximum number of rows the endpoint can return at a time is 1000. You can set a lower value using the limit parameter.

If there are more rows than the limit, the API paginates the response. The JSON response sets has_next_page to true and returns a next_cursor value. To fetch the next page, pass that value back as the cursor query parameter, keeping the other parameters the same.

warning

The cursor is an opaque bookmark tied to the exact query that produced it. When fetching subsequent pages, keep start_date, end_date, and user_email identical to the original request and change only the cursor. Changing any other parameter while paginating can cause rows to be duplicated or skipped.

curl -H 'X-Figma-Token: <TOKEN>' 'https://api.figma.com/v1/ai_usage/daily?start_date=2026-05-01&end_date=2026-05-31&cursor=<NEXT_CURSOR>'

When has_next_page is false, next_cursor is an empty string and there are no more rows to fetch.