Get metrics bulk data API

Bulk metric data retrieval via API

Use this API to retrieve data for multiple metrics in a single request, across versions, scenarios, time ranges, granularities, and dimensions.

This endpoint is optimized for bulk reads and reduces the need to make repeated calls for individual metrics.

API Endpoint

POST

https://<tenant_id>.drivetrain.ai/drive/api/v1/public/metrics-bulk

API structure

Request {
  metricNames : List<String>
  versions    : List<String>
  scenarios   : List<String>
  granularity : List<String>
  startDate   : String
  endDate     : String
  dimensions  : List<String>   // pivot dimension rows
}

All parameters use Backend names where applicable. List parameters can contain one or more values unless stated otherwise.

Sample response

{
  data: [
    {
      t        : <date>,
      val      : <number>,
      <dimension_name> : <dimension_value>,
      metric   : <metric_backend_name>,
      version  : <version_backend_name>,
      scenario : <scenario_backend_name>
    }
  ]
}

Each record represents a unique combination of metric, time period, version, scenario, and dimension values.

Request body parameters

metricNames (MANDATORY)

• Backend names of metrics or variables.

• Backend name can be:

  • Copied from the metric URL in Drivetrain.

  • Retrieved from the SMPP page for variables.

  • A meta API will be introduced to map Backend names ↔ Display names.

versions (OPTIONAL)

• Defaults to Actuals if not provided.

• Multiple versions can be specified.

• Version names must be Backend names.

• Backend names for versions will be exposed via a meta API.

scenarios (OPTIONAL)

• Scenario Backend names.

• Behavior depends on versions:

  • If only Actuals is requested → scenarios are ignored.

  • If other versions are requested:

    • Defaults to Base Case if scenarios are not specified.

granularity (OPTIONAL)

• Defaults to MONTHLY.

• Supported values:

  • WEEKLY

  • MONTHLY

  • QUARTERLY

  • YEARLY

startDate and endDate (MANDATORY)

• Defines the time range for which data is returned.

• Both parameters must be provided.

dimensions (OPTIONAL)

• List of pivot dimensions (row dimensions).

• If omitted, only aggregated metric values are returned.

• Constraints and behavior:

  • Maximum of 5 dimensions allowed.

  • Dimensions not applicable to a metric are automatically skipped.

  • If a dimension is not present in a given version, values for that dimension cut are not returned.

  • When multiple dimensions are specified, results are aggregated in the order provided.

Example

If a metric varies by Product and Region, and both are specified, results are returned at the Product × Region level.

Headers

Header	Required
apikey	Yes
Content-Type: application/json	Yes

Sample response

{
  "data": [
    {
      "t": "2025-01-01",
      "val": 100,
      "Region": "NAMER",
      "metric": "metrics.ARR",
      "version": "Actuals",
      "scenario": "Base_Case"
    }
  ]
}

Response fields

• t : Time period corresponding to the selected granularity

• val : Metric value

• metric : Metric Backend name

• version : Version Backend name

• scenario : Scenario Backend name

• dimension fields : One field per requested dimension

Validation rules & error handling

Condition	Result
More than 50 metrics requested	400 Bad Request
More than 5 dimensions specified	400 Bad Request
Unsupported granularity	400 Bad Request
Invalid metric or version name	400 Bad Request

Test scenarios

Without dimensions

• Fetch a single metric

• Fetch multiple metrics (Base version & scenario)

• Fetch a single metric across versions

• Fetch a single metric across scenarios

• Fetch a single metric across versions and scenarios

• Fetch multiple metrics across versions and scenarios

• Fetch more than 50 metrics → 400 Bad Request

With dimensions

• Fetch a single metric with one dimension

• Fetch a single metric with two dimensions (observe cross-product behavior)

• Fetch a single metric with more than 5 dimensions → 400 Bad Request

• Repeat all above cases across:

  • Versions

  • Scenarios

  • Versions + scenarios (Use distinct metric and dimension values to validate correctness)

Related

Get metrics list API

Get metric data API