Method: projects.timeSeries.query

Queries time series by using Monitoring Query Language (MQL). We recommend using PromQL instead of MQL. For more information about the status of MQL, see the MQL deprecation notice.

HTTP request

POST https://monitoring.googleapis.com/v3/{name}/timeSeries:query

Path parameters

Parameters
name

string

Required. The project on which to execute the request. The format is:

projects/[PROJECT_ID_OR_NUMBER]

Request body

The request body contains data with the following structure:

JSON representation
{
  "query": string,
  "pageSize": integer,
  "pageToken": string
}
Fields
query

string

Required. The query in the Monitoring Query Language format. The default time zone is in UTC.

pageSize

integer

A positive number that is the maximum number of timeSeriesData to return.

pageToken

string

If this field is not empty then it must contain the nextPageToken value returned by a previous call to this method. Using this field causes the method to return additional results from the previous method call.

Response body

The timeSeries.query response. For information about the status of Monitoring Query Language (MQL), see the MQL deprecation notice.

If successful, the response body contains data with the following structure:

JSON representation
{
  "timeSeriesDescriptor": {
    object (TimeSeriesDescriptor)
  },
  "timeSeriesData": [
    {
      object (TimeSeriesData)
    }
  ],
  "nextPageToken": string,
  "partialErrors": [
    {
      object (Status)
    }
  ]
}
Fields
timeSeriesDescriptor

object (TimeSeriesDescriptor)

The descriptor for the time series data.

timeSeriesData[]

object (TimeSeriesData)

The time series data.

nextPageToken

string

If there are more results than have been returned, then this field is set to a non-empty value. To see the additional results, use that value as pageToken in the next call to this method.

partialErrors[]

object (Status)

Query execution errors that may have caused the time series data returned to be incomplete. The available data will be available in the response.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/monitoring
  • https://www.googleapis.com/auth/monitoring.read

For more information, see the Authentication Overview.

TimeSeriesDescriptor

A descriptor for the labels and points in a time series.

JSON representation
{
  "labelDescriptors": [
    {
      object (LabelDescriptor)
    }
  ],
  "pointDescriptors": [
    {
      object (ValueDescriptor)
    }
  ]
}
Fields
labelDescriptors[]

object (LabelDescriptor)

Descriptors for the labels.

pointDescriptors[]

object (ValueDescriptor)

Descriptors for the point data value columns.

ValueDescriptor

A descriptor for the value columns in a data point.

JSON representation
{
  "key": string,
  "valueType": enum (ValueType),
  "metricKind": enum (MetricKind),
  "unit": string
}
Fields
key

string

The value key.

valueType

enum (ValueType)

The value type.

metricKind

enum (MetricKind)

The value stream kind.

unit

string

The unit in which timeSeries point values are reported. unit follows the UCUM format for units as seen in https://unitsofmeasure.org/ucum.html. unit is only valid if valueType is INTEGER, DOUBLE, DISTRIBUTION.

TimeSeriesData

Represents the values of a time series associated with a TimeSeriesDescriptor.

JSON representation
{
  "labelValues": [
    {
      object (LabelValue)
    }
  ],
  "pointData": [
    {
      object (PointData)
    }
  ]
}
Fields
labelValues[]

object (LabelValue)

The values of the labels in the time series identifier, given in the same order as the labelDescriptors field of the TimeSeriesDescriptor associated with this object. Each value must have a value of the type given in the corresponding entry of labelDescriptors.

pointData[]

object (PointData)

The points in the time series.

LabelValue

A label value.

JSON representation
{

  // Union field value can be only one of the following:
  "boolValue": boolean,
  "int64Value": string,
  "stringValue": string
  // End of list of possible types for union field value.
}
Fields
Union field value. The label value can be a bool, int64, or string. value can be only one of the following:
boolValue

boolean

A bool label value.

int64Value

string (int64 format)

An int64 label value.

stringValue

string

A string label value.

PointData

A point's value columns and time interval. Each point has one or more point values corresponding to the entries in pointDescriptors field in the TimeSeriesDescriptor associated with this object.

JSON representation
{
  "values": [
    {
      object (TypedValue)
    }
  ],
  "timeInterval": {
    object (TimeInterval)
  }
}
Fields
values[]

object (TypedValue)

The values that make up the point.

timeInterval

object (TimeInterval)

The time interval associated with the point.