---
title: "Query timeseries points"
method: GET
path: "/api/v1/query"
tags: ["Metrics"]
---

# Query timeseries points

`GET /api/v1/query`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v1/query`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `timeseries_query`

Query timeseries points.

## Query parameters

- `from` integer, required
- `to` integer, required
- `query` string, required

## Response `200`

OK

- MetricsQueryResponse: Response Object that includes your query and the list of metrics retrieved.
  - `error` string: Message indicating the errors if status is not `ok`.
  - `from_date` integer: Start of requested time window, milliseconds since Unix epoch.
  - `group_by` string[]: List of tag keys on which to group.
  - `message` string: Message indicating `success` if status is `ok`.
  - `query` string: Query string
  - `res_type` string: Type of response.
  - `series` MetricsQueryMetadata[]: List of timeseries queried.
    - `aggr` string, nullable: Aggregation type.
    - `display_name` string: Display name of the metric.
    - `end` integer: End of the time window, milliseconds since Unix epoch.
    - `expression` string: Metric expression.
    - `interval` integer: Number of milliseconds between data samples.
    - `length` integer: Number of data samples.
    - `metric` string: Metric name.
    - `pointlist` Point[]: List of points of the timeseries in milliseconds.
      - number[]: Array of timeseries points.
    - `query_index` integer: The index of the series' query within the request.
    - `scope` string: Metric scope, comma separated list of tags.
    - `start` integer: Start of the time window, milliseconds since Unix epoch.
    - `tag_set` string[]: Unique tags identifying this series.
    - `unit` MetricsQueryUnit[]: Detailed information about the metric unit. The first element describes the "primary unit" (for example, `bytes` in `bytes per second`). The second element describes the "per unit" (for example, `second` in `bytes per second`). If the second element is not present, the API returns null.
      - `family` string: Unit family, allows for conversion between units of the same family, for scaling.
      - `name` string: Unit name
      - `plural` string: Plural form of the unit name.
      - `scale_factor` number, double: Factor for scaling between units of the same family.
      - `short_name` string: Abbreviation of the unit.
  - `status` string: Status of the query.
  - `to_date` integer: End of requested time window, milliseconds since Unix epoch.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `429`: Too many requests

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v1-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v1-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v1-collection/revisions/ca5871004d26?raw)