HTTP API Reference

Usage API reference

Reference documentation for the Usage API

The Usage API reports metered usage, such as API requests, documents and function invocations, for a Sanity project, media library or organization. A snapshot gives the usage so far within a day, month or year. History gives usage over a date range, grouped by day, month or year, with optional running totals.

Authentication

Base API server URL

Production environment

https://api.sanity.io

Resources

Get resource usage.

Get resource usage snapshot

get/v2026-09-01/usage/{resourceType}/{resourceId}/snapshot

Returns resource usage snapshot for a specific resource.

Path parameters

  • resourceTypestringrequired

    Type of the resource that we are querying for. Any other value is rejected with a 400.

    Example:organization
  • resourceIdstringrequired

    ID of the resource (project, media library or organization) that we are querying for

    Example:or0Bc1hcJ

Query parameters

  • metricsstring

    Comma-separated list of metrics that we want to get in the response.

    Example:apicdnrequests,documents,assets
  • datestring (date)

    Date for which to fetch the snapshot, in ISO format (e.g. 2017-09-14). Defaults to today's date.

  • periodstring

    Billing period for which to fetch the snapshot, valid values are day, month, year. Defaults to month. Example: date=2017-09-14 with period=month will return usage from 2017-09-01 to 2017-09-14, while the same date with period=year will return usage from 2017-01-01 to 2017-09-14 (defaults to snapshotPeriod=startOfPeriod).

  • snapshotPeriodstring

    Accepts previousPeriod and startOfPeriod. If snapshotPeriod is set to previousPeriod, then a snapshot period will be used strictly. Example: with date=2017-09-14, period=month and snapshotPeriod=previousPeriod will return usage from 2017-08-15 to 2017-09-14, while the same date with period=year and snapshotPeriod=previousPeriod will return usage from 2016-09-15 to 2017-09-14. Defaults to startOfPeriod

Responses

200

Resource usage snapshot for the requested period.

  • resourceTypestring
    Example:organization
  • resourceIdstring
    Example:or0Bc1hcJ
  • usageobject

    Map of metric names to their value for the snapshot period. Values can be fractional.

    Example
    {"apirequests":14,"standard-function-gb-seconds":12.01}
  • timestampsobject

    Map of metric names to the latest timestamp recorded in the period, or null when the metric has no data.

    Example
    {"apirequests":"2025-02-13T00:00:00Z","users":null}

Get resource usage history

get/v2026-09-01/usage/{resourceType}/{resourceId}/history

Returns resource usage history for a specific resource.

Path parameters

  • resourceTypestringrequired

    Type of the resource that we are querying for. Any other value is rejected with a 400.

    Example:organization
  • resourceIdstringrequired

    ID of the resource (project, media library or organization) that we are querying for

    Example:or0Bc1hcJ

Query parameters

  • metricsstring

    Comma-separated list of metrics that we want to get in the response.

    Example:apicdnrequests,documents,assets
  • fromstring (date)

    Date from which to fetch history, in ISO format (e.g. 2017-09-14). Defaults to 30 days before today. Will not be aligned with period, so make sure it is set to the first day in the period if this is required.

  • tostring (date)

    Date up to which to fetch history, in ISO format (e.g. 2017-09-14). Defaults to today's date. Will not be aligned with period, so make sure it is set to the last day in the period if this is required.

  • periodstring

    Period for which to aggregate usage, valid values are day, month, and year. Defaults to month. The requested range is limited by the period: day accepts at most 90 days between from and to, month at most 24 calendar months, and year is unlimited. Exceeding the limit is rejected with a 400.

  • cumulativeboolean

    If true, calculate cumulative usage (running total) for counter type metrics instead of the usage within each individual period. Defaults to false.

  • cumulative_periodstring

    Period after which the cumulative usage will reset to 0. E.g. cumulative usage with period=day and cumulative_period=month will calculate cumulative total within each. The period is locked to the calendar. Defaults to forever.

Responses

200

Resource usage history, wrapped in a resource envelope.

  • resourceTypestring
    Example:organization
  • resourceIdstring
    Example:or0Bc1hcJ
  • dataarray
    Show child attributes
    items
    • datestring

      Start of the aggregation period, formatted according to the requested period (e.g. 2024-11-05 for day, 2024-11 for month, 2024 for year).

      Example:2024-11
    • metricsobject

      Map of metric names to their aggregated value for this period.

      Example
      {"apirequests":563,"agent-actions":563}
    • cumulativeobject

      Map of metric names to their running total for counter metrics. Only present when cumulative=true was requested.

      Example
      {"apirequests":1126,"agent-actions":1126}

Get scoped resource usage snapshot

get/v2026-09-01/usage/{resourceType}/{resourceId}/{scope}/snapshot

Returns resource usage snapshot grouped by scope (e.g., per-user usage within an organization). User-scoped metrics exist only for organizations: content-agent-queries, content-agent-actions, content-agent-queries-ai-usage, content-agent-actions-ai-usage, ai-usage, embeddings-writes and embeddings-reads. Other metrics and resource types return no scoped data.

Path parameters

  • resourceTypestringrequired

    Type of the resource that we are querying for. Any other value is rejected with a 400.

    Example:organization
  • resourceIdstringrequired

    ID of the resource (project, media library or organization) that we are querying for

    Example:or0Bc1hcJ
  • scopestringrequired

    Scope level for grouping usage metrics. Currently only 'user' is supported.

    Example:user

Query parameters

  • metricsstring

    Comma-separated list of metrics that we want to get in the response.

    Example:apicdnrequests,documents,assets
  • datestring (date)

    Date for which to fetch the snapshot, in ISO format (e.g. 2017-09-14). Defaults to today's date.

  • periodstring

    Billing period for which to fetch the snapshot, valid values are day, month, year. Defaults to month. Example: date=2017-09-14 with period=month will return usage from 2017-09-01 to 2017-09-14, while the same date with period=year will return usage from 2017-01-01 to 2017-09-14 (defaults to snapshotPeriod=startOfPeriod).

  • snapshotPeriodstring

    Accepts previousPeriod and startOfPeriod. If snapshotPeriod is set to previousPeriod, then a snapshot period will be used strictly. Example: with date=2017-09-14, period=month and snapshotPeriod=previousPeriod will return usage from 2017-08-15 to 2017-09-14, while the same date with period=year and snapshotPeriod=previousPeriod will return usage from 2016-09-15 to 2017-09-14. Defaults to startOfPeriod

Responses

200

Scoped usage snapshot

  • resourceTypestring
    Example:organization
  • resourceIdstring
    Example:or0Bc1hcJ
  • scopestring
    Example:user
  • dataarray
    Show child attributes
    items
    • idstring

      Identifier of the scoped entity (e.g., user ID)

      Example:user-123
    • usageobject

      Map of metric names to their values

      Example
      {"content-agent-queries":150,"content-agent-actions":45}
    • timestampsobject

      Map of metric names to their last recorded timestamps

      Example
      {"content-agent-queries":"2024-12-12T13:48:25.727Z","content-agent-actions":"2024-12-12T12:30:00.000Z"}

Get scoped resource usage history

get/v2026-09-01/usage/{resourceType}/{resourceId}/{scope}/history

Returns resource usage history grouped by scope (e.g., per-user usage history within an organization). User-scoped metrics exist only for organizations: content-agent-queries, content-agent-actions, content-agent-queries-ai-usage, content-agent-actions-ai-usage, ai-usage, embeddings-writes and embeddings-reads. Other metrics and resource types return no scoped data.

Path parameters

  • resourceTypestringrequired

    Type of the resource that we are querying for. Any other value is rejected with a 400.

    Example:organization
  • resourceIdstringrequired

    ID of the resource (project, media library or organization) that we are querying for

    Example:or0Bc1hcJ
  • scopestringrequired

    Scope level for grouping usage metrics. Currently only 'user' is supported.

    Example:user

Query parameters

  • metricsstring

    Comma-separated list of metrics that we want to get in the response.

    Example:apicdnrequests,documents,assets
  • fromstring (date)

    Date from which to fetch history, in ISO format (e.g. 2017-09-14). Defaults to 30 days before today. Will not be aligned with period, so make sure it is set to the first day in the period if this is required.

  • tostring (date)

    Date up to which to fetch history, in ISO format (e.g. 2017-09-14). Defaults to today's date. Will not be aligned with period, so make sure it is set to the last day in the period if this is required.

  • periodstring

    Period for which to aggregate usage, valid values are day, month, and year. Defaults to month. The requested range is limited by the period: day accepts at most 90 days between from and to, month at most 24 calendar months, and year is unlimited. Exceeding the limit is rejected with a 400.

Responses

200

Scoped usage history

  • resourceTypestring
    Example:organization
  • resourceIdstring
    Example:or0Bc1hcJ
  • scopestring
    Example:user
  • dataarray
    Show child attributes
    items
    • datestring

      Period for the history point

      Example:2024-11
    • usagearray
      Show child attributes
      items
      • idstring

        Identifier of the scoped entity (e.g., user ID)

        Example:user-123
      • metricsobject

        Map of metric names to their values for this period

        Example
        {"content-agent-queries":50,"content-agent-actions":15}
Sanity logosanity.ioAll Systems Operational© Sanity 2026
Change site theme