Query consumption metrics (legacy)

Using the OptiTech API, you can query project-level consumption metrics with the legacy endpoint. The Management API only allows this path for Scale plans and above (legacy Scale, Business, and Enterprise, and usage-based Scale and higher). It is not available on Launch; use GET /consumption_history/v2/projects instead. On every eligible plan, this endpoint returns legacy metrics only (active time, compute time, written data, synthetic storage). On a usage-based plan, those metrics do not match your invoice; for invoice-aligned metrics use the project metrics endpoint in Query consumption metrics.

Issuing calls to these APIs does not wake a project's compute endpoints.

Request overview

The legacy endpoints return consumption data for legacy billing plans. Date format, range limits, and granularity are the same as the usage-based endpoint; for details see Date format, range, and granularity in Query consumption metrics. Consumption history is available from March 1, 2024, at 00:00:00 UTC.

Metrics

Both endpoints return metrics that align with legacy billing. Default metrics are returned unless you specify otherwise with the metrics parameter:

Project-level endpoint

Endpoint:

GET https://console.optitech.com/api/v2/consumption_history/projects

Retrieves consumption metrics per project at the chosen granularity. The same Scale plans and above access rule applies as for the account endpoint (not available on Launch—use v2 project metrics instead). Results are ordered by time in ascending order (oldest to newest). History begins at the time of upgrade. Issuing a call to this API does not wake a project's compute endpoint.

Required parameters

• from (date-time, required): Start of the consumption period in RFC 3339 format. The value is rounded according to the specified granularity. Consumption history is available from March 1, 2024, at 00:00:00 UTC. The range must respect the granularity limits (hourly: last 168 hours; daily: last 60 days; monthly: last year).
• to (date-time, required): End of the consumption period in RFC 3339 format. The value is rounded according to the specified granularity. The range must respect the same granularity limits as from.
• granularity (string, required): Granularity of consumption metrics. hourly (last 168 hours), daily (last 60 days), or monthly (last year).

Optional parameters

• project_ids (array of strings, 0-100 items): Filter to specific project IDs. If omitted, the response contains all projects. Can be an array of parameter values or a comma-separated list in a single parameter value.
• org_id (string): Organization for which to return project consumption metrics. If not provided, returns metrics for the authenticated user's projects.
• metrics (array of strings): Metrics to include. If omitted, active_time_seconds, compute_time_seconds, written_data_bytes, and synthetic_storage_size_bytes are returned. Possible values: active_time_seconds, compute_time_seconds, written_data_bytes, synthetic_storage_size_bytes, data_storage_bytes_hour, logical_size_bytes, logical_size_bytes_hour. Can be an array or comma-separated list.
• limit (integer, 1-100): Number of projects in the response. Default: 10.
• cursor (string): Cursor value from the previous response to get the next batch of projects.

The include_v1_metrics parameter is deprecated; use metrics instead. If metrics is specified, include_v1_metrics is ignored.

Legacy metric definitions

Default metrics (returned when metrics is omitted):

• active_time_seconds: Seconds. The amount of time the compute endpoints have been active.
• compute_time_seconds: Seconds. The number of CPU seconds used by compute endpoints, including compute endpoints that have been deleted. For example: 1 CPU for 1 second = 1; 2 CPUs for 1 second = 2.
• written_data_bytes: Bytes. The amount of written data for all branches.
• synthetic_storage_size_bytes: Bytes. The space occupied in storage. Synthetic storage size combines the logical data size and Write-Ahead Log (WAL) size for all branches.

Additional metrics (include via the metrics parameter):

• data_storage_bytes_hour: Bytes-Hour. The amount of storage consumed hourly.
• logical_size_bytes: Bytes. The amount of logical size consumed.
• logical_size_bytes_hour: Bytes-Hour. The amount of logical size consumed hourly.

Example request and response

Replace $OPTITECH_API_KEY with your API key and include org_id if needed.

Project-level

curl --request GET \
  --url 'https://console.optitech.com/api/v2/consumption_history/projects?from=2024-06-30T00:00:00Z&to=2024-07-02T00:00:00Z&granularity=daily&org_id=org-ocean-art-12345678&limit=10' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer $OPTITECH_API_KEY'

{
  "projects": [
    {
      "project_id": "random-project-123456",
      "periods": [
        {
          "period_id": "random-period-abcdef",
          "period_plan": "scale",
          "period_start": "2024-06-01T00:00:00Z",
          "period_end": "2024-07-01T00:00:00Z",
          "consumption": [
            {
              "timeframe_start": "2024-06-30T00:00:00Z",
              "timeframe_end": "2024-07-01T00:00:00Z",
              "active_time_seconds": 147472,
              "compute_time_seconds": 43222,
              "written_data_bytes": 112730864,
              "synthetic_storage_size_bytes": 37000959232
            },
            {
              "timeframe_start": "2024-07-01T00:00:00Z",
              "timeframe_end": "2024-07-02T00:00:00Z",
              "active_time_seconds": 1792,
              "compute_time_seconds": 533,
              "written_data_bytes": 0,
              "synthetic_storage_size_bytes": 0
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "cursor": "random-project-123456"
  }
}

For full parameter and response details, see Retrieve project consumption metrics in the OptiTech API Reference.

The following sections cover paging (project endpoint), polling behavior, and handling errors.

Pagination

The project-level endpoint uses cursor-based pagination. The response includes a pagination object with a cursor value (the project ID of the last project in the list). To get the next page, send another request with that cursor in the query string and the same from, to, and granularity as your first request.

Example request for the next page (using the cursor from the previous response):

curl --request GET \
     --url 'https://console.optitech.com/api/v2/consumption_history/projects?cursor=divine-tree-77657175&limit=10&from=2024-06-30T00%3A00%3A00Z&to=2024-07-02T00%3A00%3A00Z&granularity=daily&org_id=org-ocean-art-12345678' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $OPTITECH_API_KEY'

In the URL above, the cursor parameter is cursor=divine-tree-77657175. Replace that value with the cursor from your previous response's pagination object.

Consumption polling

OptiTech's consumption data is updated approximately every 15 minutes. A minimum interval of 15 minutes between API calls is recommended. For reporting or invoicing, you can pull usage data at that interval or choose your own; OptiTech does not dictate how often you poll or how you bill your users.

The legacy and usage-based consumption API endpoints share a single rate limiter of approximately 50 requests per minute per account. OptiTech uses a token bucket approach, which refills at a steady rate and allows short bursts within the bucket size, so the limit behaves like a sliding window rather than a fixed reset every minute. For more details, see Token bucket.

Calling the consumption APIs does not wake computes that have been suspended due to inactivity, so polling will not increase your consumption.

The endpoints on this page return legacy metrics only; when your organization is eligible (Scale+), you can call them on legacy or usage-based plans, but responses will not match your invoice on a usage-based plan. For metrics that match your invoice—or for Launch plans—see Query consumption metrics.

Error responses

Common error responses you may encounter:

• 403 Forbidden: These endpoints are not available for your plan. The API response states that access is included with Scale plans and above (legacy Scale, Business, and Enterprise, and usage-based Scale and higher—not Launch).
• 404 Not Found: Account is not a member of the organization specified by org_id.
• 406 Not Acceptable: The specified date-time range is outside the boundaries of the specified granularity. Adjust your from and to values or select a different granularity.
• 429 Too Many Requests: Too many requests. Wait before retrying.

Usage-based pricing and legacy API limitations

The legacy endpoints on this page were designed for OptiTech's legacy billing plans and do not align with usage-based plans. If you're on a usage-based plan (Launch, Scale, Agent, or Enterprise), use Query consumption metrics for metrics that map to your invoice.

Legacy API: Uses synthetic_storage_size_bytes (logical data + WAL for all branches in one metric).

Usage-based API: Returns separate metrics that match your invoice: root_branch_bytes_month, child_branch_bytes_month, instant_restore_bytes_month, snapshot_storage_bytes_month, public_network_transfer_bytes, private_network_transfer_bytes, extra_branches_month, and compute_unit_seconds. The legacy APIs do not provide these. Use the project metrics endpoint in Query consumption metrics to retrieve them.