# Get metrics bulk data 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
}
```

{% hint style="info" %}
All parameters use **Backend names** where applicable. List parameters can contain one or more values unless stated otherwise.
{% endhint %}

**Sample response**

```
{
  data: [
    {
      t        : <date>,
      result   : <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 Actual 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 Actual 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",
      "result": 100,
      "Region": "NAMER",
      "metric": "metrics.ARR",
      "Version": "Actual",
      "scenario": "Base_Case"
    }
  ]
}
```

#### Response fields

* **`t`** : Time period corresponding to the selected granularity
* **`result`** : 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](/extending-drivetrain/drivetrain-api/get-metric-list-api.md)

[Get metric data API](broken://pages/5yOiTKMVf3rLq1Z2sLMw)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://integrations.drivetrain.ai/extending-drivetrain/drivetrain-api/get-metrics-bulk-data-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.