Skip to main content

Metrics APIs

Thumbnail icon

The Metrics Query API lets you execute Metrics queries from third-party scripts and applications so that you can reformat the results as desired.

Refer to Getting Started for Sumo Logic API Authentication, Endpoints, and Security.

Our APIs are built with OpenAPI. You can generate client libraries in several languages and explore automated testing.

To access our API documentation, navigate to the appropriate link based on your Sumo deployment. Deployment types differ based on geographic location and account creation date. If unsure, see How to determine your endpoint.


You will need:

Endpoints for API access

Sumo Logic has deployments that are assigned depending on the geographic location and the date an account is created. For API access, you must manually direct your API client to the correct Sumo Logic API URL.

See Sumo Logic Endpoints for the list of the URLs.

An HTTP 301 Moved error suggests that the wrong endpoint was specified.

Rate limiting

  • A rate limit of four API requests per second (240 requests per minute) applies to all API calls from a user.
  • A rate limit of 10 concurrent requests to any API endpoint applies to an access key.

If a rate is exceeded, a rate limit exceeded 429 status code is returned.


The APIs return operation failures with a description and error code, including the following generic errors that apply to all APIs:

301movedThe requested resource SHOULD be accessed through returned URI in Location Header.
401unauthorizedCredential could not be verified.
403forbiddenThis operation is not allowed for your account type.
404notfoundRequested resource could not be found.
405method.unsupportedUnsupported method for URL.
415contenttype.invalidInvalid content type.
429rate.limit.exceededThe API request rate is higher than 4 request per second.
500internal.errorInternal server error.
503service.unavailableService is currently unavailable.

API details

Executing a query

To execute a metrics query, send a JSON request to the endpoint.

Method: POST

Example endpoint:

Which API endpoint should I use?

To determine which Sumo Logic API endpoint you should use, find the deployment pod referenced in your browser's Sumo Logic service URL.

If you see, for example, that means you're running on the US2 pod and need to use the API endpoint For the service URL, you'd need to use the API endpoint, and so on. The only exception is the US1 pod (, which uses the API endpoint

To view all available endpoints, see Sumo Logic Endpoints.



Query request parameters

query[QueryWithRowId]YesThe actual query expressions.
startTimelongYesStart of the query time range, in milliseconds since epoch.
endTimelongYesEnd of the query time range, in milliseconds since epoch.
requestedDataPointsintNoDesired number of data points returned per series.
maxDataPointsIntNoUpper bound on number of data points returned per series
maxTotalDataPointsIntNoUpper bound on sum total number of data points returned across all series.
desiredQuantizationInSecIntNoDesired granularity of temporal quantization in seconds. Note that this may be overridden by the backend in order to satisfy constraints on the number of data points returned.

QueryWithRowId object

queryStringYesThe actual metrics search expression.
rowIdStringYesName or alias for this “row” of the query.

Status codes

200SuccessThe query has been successfully executed.
400Bad RequestGeneric request error by the client.
415Unsupported Media TypeContent-Type wasn't set to application/json.

Query Result

The result will be a JSON document containing results (or an error) for each query row in the “query” argument.

response[MetricsErrorsOrResults]Results (or error) for each row-query.
queryInfoMetricsQueryInfoInformation about the original user query.

MetricsQueryInfo object

startTimelongStart of the query time range, in milliseconds since epoch.
endTimelongEnd of the query time range, in milliseconds since epoch.
desiredQuantizationInSecsintOriginal user-supplied desired granularity of temporal quantization (if supplied).
actualQuantizationInSecsintActual granularity of temporal quantization used by the back-end for query.

MetricsDatapointsError object

(extends MetricsErrorsOrResults)

rowIdStringName or alias for this “row” of the query.
messageTypeStringError type.
messageStringError message.

MetricsDataPointsResult object

(extends MetricsErrorsOrResults)

rowIdStringName or alias for this “row” of the query.
results[MetricsRowResult]Actual retrieved and computed values for series returned by this row’s query.


metricMetricDefFull metric definition for this result.
datapointsMetricsDataPointsThe actual results.


dimensions[MetricDim]Identifying dimensions for this metric.
algoIdlongInternal identifier for the outlier detection algorithm used in these results.


keystringKey name for this dimension.
valuestringAssociated value for this key.


timestamp[long]Timestamps (milliseconds since epoch) for each data point.
value[float]Actual numerical values for reach data point.
outlierParamsInternal parameters for outlier detection.
Max[float]Maximum aggregate.
Min[float]Minimum aggregate.
Avg[float]Average aggregate.
Count[int]Count of raw observations

Example Use

Example use of this API can be seen in this Python script, which queries the API and reformats the results into a pandas time series DataFrame.

To use this script, set the (user, pw) variables and run these commands from an IPython or Jupyter notebook:

df = exampleQuery(user, pw, query)

You should get a resulting plot like below, and df should contain your data nicely formatted as a time series pandas DataFrame.

Privacy Statement
Terms of Use

Copyright © 2024 by Sumo Logic, Inc.