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.

Sumo Logic has several deployment types, which vary by geographic location and the date an account is created. Select the documentation link below that corresponds to your deployment. If you're not sure, see How to determine your endpoint.

Before You Begin

You will need:

  • An Enterprise account. For more information, see Cloud Flex or Cloud Flex Credits, depending on the Sumo Logic packaging you have.
  • An access key/access ID for authentication. Username/password are not supported.

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.

Errors

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

CodeErrorDescription
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: https://api.sumologic.com/api/v1/metrics/results

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 https://service.us2.sumologic.com, for example, that means you're running on the US2 pod and need to use the API endpoint https://api.us2.sumologic.com/api/. For the service URL https://service.eu.sumologic.com, you'd need to use the API endpoint https://api.eu.sumologic.com/api/, and so on. The only exception is the US1 pod (https://service.sumologic.com), which uses the API endpoint https://api.sumologic.com/api/.

To view all available endpoints, see Sumo Logic Endpoints.

Headers

HeaderValue
Content-Typeapplication/json
Acceptapplication/json

Query request parameters

ParameterTypeRequiredDescription
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

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

Status codes

CodeTextDescription
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.

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

MetricsQueryInfo object

ParameterTypeDescription
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)

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

MetricsDataPointsResult object

(extends MetricsErrorsOrResults)

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

MetricsRowResult

ParameterTypeDescription
metricMetricDefFull metric definition for this result.
datapointsMetricsDataPointsThe actual results.

MetricDef

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

MetricDim

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

MetricsDataPoints

ParameterTypeDescription
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)
df.fillna(method='backfill').plot()
plt.show()

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

Legal
Privacy Statement
Terms of Use

Copyright © 2024 by Sumo Logic, Inc.