#Usage metrics API reference

The Hygraph Management API gives you programmatic access to your project's usage and safeguard metrics. You can use this data to build external dashboards or set up alerting for your own monitoring stack. This data is also available in the Usage dashboard.

#Prerequisites

To query usage metrics, your Permanent Auth Token must include the Read observability data Management API permission. For more information, see Management API permissions.

#Query structure

On the Management API, the usage field exists on:

viewer.project: Project-level metrics.
viewer.project.environment: Environment-level metrics.

viewer {
  project(id: $projectId) {
    usage(end: $end, start: $start) {
      # project-level metrics
    }
    environment(id: $environmentId) {
      usage(end: $end, start: $start) {
        # environment-level metrics
      }
    }
  }
}

Replace $projectId and $environmentId with the IDs from your project settings. You can find the Project ID and environment ID in the project URL: https://app.hygraph.com/<projectId>/<environmentId>/.

#Arguments

Argument	Type	Description
`end`	`DateTime!`	End of the requested date range.
`start`	`DateTime!`	Start of the requested date range. The API only returns data within your plan’s retention window.

Retention depends on your plan:

Hobby plans: 30 days
Paid plans: 365 days

Requesting a start date earlier than your retention window does not return an error. The API clips the start to the earliest retained date and returns data from that point forward.

#Metrics

#Billing metrics

Billing metrics are summed across all environments at project level. These metrics reflect consumption against your plan limits.

Field	Units	Description
`apiOperations`	Request count per day	External Content API requests, excluding Studio traffic. Aggregated for usage reporting.
`assetTraffic`	Bytes per day	Asset data transferred, counted toward asset bandwidth usage.

#Technical safeguard metrics

Technical safeguard metrics relate to the same limits as API limits. They exist on both project and environment usage. For interpreting these limits, environment usage is usually the best match, because limits apply per environment.

At project level (viewer.project { usage }):

maxRps*, maxConcurrency*, maxRequestSize*: For each day in the range, the maximum value observed across all environments. This is the largest per-environment value for that day, not a single merged peak across the whole project.
*OverLimit*: For each day in the range, the total count across all environments.

At environment level (viewer.project.environment { usage }):

maxRps*, maxConcurrency*, maxRequestSize*: For each day in the range, the maximum value observed for that environment only.
*OverLimit*: For each day in the range, the total count for that environment only.

Field	Description
`maxRpsQueries`	Peak requests per second for queries.
`maxRpsMutations`	Peak requests per second for mutations.
`maxConcurrencyQueries`	Peak in-flight concurrent operations for queries.
`maxConcurrencyMutations`	Peak in-flight concurrent operations for mutations.
`maxRequestSizeQueries`	Largest GraphQL payload size observed for queries.
`maxRequestSizeMutations`	Largest GraphQL payload size observed for mutations.
`rpsOverLimitQueries`	Requests that exceeded the RPS limit for queries.
`rpsOverLimitMutations`	Requests that exceeded the RPS limit for mutations.
`concurrencyOverLimitQueries`	Requests that exceeded the concurrency limit for queries.
`concurrencyOverLimitMutations`	Requests that exceeded the concurrency limit for mutations.
`requestSizeOverLimitQueries`	Requests that exceeded the request size limit for queries.
`requestSizeOverLimitMutations`	Requests that exceeded the request size limit for mutations.

#Response

Field	Type	Description
`timestamps`	`[DateTime!]!`	Start of each day in the date range.
`values`	`[Float!]!`	One value per day in the date range, in the same order.

Metrics update once per day and responses are cached for a short interval. Avoid polling more frequently than every few minutes. Data for the current day may be incomplete; use the previous day's data for reliable trend analysis.

#Example query

This query returns project-level billing metrics and environment-level safeguard metrics over a custom date range.

Query

Response

#Usage metrics API reference

#Prerequisites

To query usage metrics, your Permanent Auth Token must include the Read observability data Management API permission. For more information, see Management API permissions.

#Query structure

On the Management API, the usage field exists on:

viewer.project: Project-level metrics.
viewer.project.environment: Environment-level metrics.

viewer {
  project(id: $projectId) {
    usage(end: $end, start: $start) {
      # project-level metrics
    }
    environment(id: $environmentId) {
      usage(end: $end, start: $start) {
        # environment-level metrics
      }
    }
  }
}

#Arguments

Argument	Type	Description
`end`	`DateTime!`	End of the requested date range.
`start`	`DateTime!`	Start of the requested date range. The API only returns data within your plan’s retention window.

Retention depends on your plan:

Hobby plans: 30 days
Paid plans: 365 days

Requesting a start date earlier than your retention window does not return an error. The API clips the start to the earliest retained date and returns data from that point forward.

#Metrics

#Billing metrics

Billing metrics are summed across all environments at project level. These metrics reflect consumption against your plan limits.

Field	Units	Description
`apiOperations`	Request count per day	External Content API requests, excluding Studio traffic. Aggregated for usage reporting.
`assetTraffic`	Bytes per day	Asset data transferred, counted toward asset bandwidth usage.

#Technical safeguard metrics

At project level (viewer.project { usage }):

maxRps*, maxConcurrency*, maxRequestSize*: For each day in the range, the maximum value observed across all environments. This is the largest per-environment value for that day, not a single merged peak across the whole project.
*OverLimit*: For each day in the range, the total count across all environments.

At environment level (viewer.project.environment { usage }):

maxRps*, maxConcurrency*, maxRequestSize*: For each day in the range, the maximum value observed for that environment only.
*OverLimit*: For each day in the range, the total count for that environment only.

Field	Description
`maxRpsQueries`	Peak requests per second for queries.
`maxRpsMutations`	Peak requests per second for mutations.
`maxConcurrencyQueries`	Peak in-flight concurrent operations for queries.
`maxConcurrencyMutations`	Peak in-flight concurrent operations for mutations.
`maxRequestSizeQueries`	Largest GraphQL payload size observed for queries.
`maxRequestSizeMutations`	Largest GraphQL payload size observed for mutations.
`rpsOverLimitQueries`	Requests that exceeded the RPS limit for queries.
`rpsOverLimitMutations`	Requests that exceeded the RPS limit for mutations.
`concurrencyOverLimitQueries`	Requests that exceeded the concurrency limit for queries.
`concurrencyOverLimitMutations`	Requests that exceeded the concurrency limit for mutations.
`requestSizeOverLimitQueries`	Requests that exceeded the request size limit for queries.
`requestSizeOverLimitMutations`	Requests that exceeded the request size limit for mutations.

#Response

Field	Type	Description
`timestamps`	`[DateTime!]!`	Start of each day in the date range.
`values`	`[Float!]!`	One value per day in the date range, in the same order.

#Example query

This query returns project-level billing metrics and environment-level safeguard metrics over a custom date range.

Query

Response

#Usage metrics API reference

#Prerequisites

To query usage metrics, your Permanent Auth Token must include the Read observability data Management API permission. For more information, see Management API permissions.

#Query structure

On the Management API, the usage field exists on:

viewer.project: Project-level metrics.
viewer.project.environment: Environment-level metrics.

viewer {
  project(id: $projectId) {
    usage(end: $end, start: $start) {
      # project-level metrics
    }
    environment(id: $environmentId) {
      usage(end: $end, start: $start) {
        # environment-level metrics
      }
    }
  }
}

#Arguments

Argument	Type	Description
`end`	`DateTime!`	End of the requested date range.
`start`	`DateTime!`	Start of the requested date range. The API only returns data within your plan’s retention window.

Retention depends on your plan:

Hobby plans: 30 days
Paid plans: 365 days

Requesting a start date earlier than your retention window does not return an error. The API clips the start to the earliest retained date and returns data from that point forward.

#Metrics

#Billing metrics

Billing metrics are summed across all environments at project level. These metrics reflect consumption against your plan limits.

Field	Units	Description
`apiOperations`	Request count per day	External Content API requests, excluding Studio traffic. Aggregated for usage reporting.
`assetTraffic`	Bytes per day	Asset data transferred, counted toward asset bandwidth usage.

#Technical safeguard metrics

At project level (viewer.project { usage }):

maxRps*, maxConcurrency*, maxRequestSize*: For each day in the range, the maximum value observed across all environments. This is the largest per-environment value for that day, not a single merged peak across the whole project.
*OverLimit*: For each day in the range, the total count across all environments.

At environment level (viewer.project.environment { usage }):

maxRps*, maxConcurrency*, maxRequestSize*: For each day in the range, the maximum value observed for that environment only.
*OverLimit*: For each day in the range, the total count for that environment only.

Field	Description
`maxRpsQueries`	Peak requests per second for queries.
`maxRpsMutations`	Peak requests per second for mutations.
`maxConcurrencyQueries`	Peak in-flight concurrent operations for queries.
`maxConcurrencyMutations`	Peak in-flight concurrent operations for mutations.
`maxRequestSizeQueries`	Largest GraphQL payload size observed for queries.
`maxRequestSizeMutations`	Largest GraphQL payload size observed for mutations.
`rpsOverLimitQueries`	Requests that exceeded the RPS limit for queries.
`rpsOverLimitMutations`	Requests that exceeded the RPS limit for mutations.
`concurrencyOverLimitQueries`	Requests that exceeded the concurrency limit for queries.
`concurrencyOverLimitMutations`	Requests that exceeded the concurrency limit for mutations.
`requestSizeOverLimitQueries`	Requests that exceeded the request size limit for queries.
`requestSizeOverLimitMutations`	Requests that exceeded the request size limit for mutations.

#Response

Field	Type	Description
`timestamps`	`[DateTime!]!`	Start of each day in the date range.
`values`	`[Float!]!`	One value per day in the date range, in the same order.

#Example query

This query returns project-level billing metrics and environment-level safeguard metrics over a custom date range.

Query

Response