Skip to main content
Sumo Logic

About Metrics API

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

The Metrics Query API lets you execute Metrics queries from third-party scripts and applications so that you can reformat the results as desired. The API follows Representational State Transfer (REST) patterns and is optimized for ease of use and consistency.

You will need:

  • An Enterprise account, see Account Types for more information.
  • 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.

API authentication

See API Authentication for a description of options for API authentication.

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

Generic errors that apply to all APIs

Code Error Description
301 moved The requested resource SHOULD be accessed through returned URI in Location Header.
401 unauthorized

 

Credential could not be verified.
403 forbidden This operation is not allowed for your account type.
404

 

notfound Requested resource could not be found.
405 method.unsupported Unsupported method for URL.
415 contenttype.invalid Invalid content type.
429 rate.limit.exceeded The API request rate is higher than 4 request per second.
500 internal.error Internal server error.
503 service.unavailable< Service 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

Sumo Logic endpoints like api.sumologic.com are different in deployments outside us1. For example, an API endpoint in Europe would begin api.eu.sumologic.com.  A service endpoint in us2 (Western US) would begin service.us2.sumologic.com.  For more information, see Sumo Logic Endpoints.

Headers

Header

Value

Content-Type

application/json

Accept

application/json

Query request parameters

Parameter

Type

Required

Description

query

[QueryWithRowId]

Yes

The actual query expressions.

startTime

long

Yes

Start of the query time range, in milliseconds since epoch.

endTime

long

Yes

End of the query time range, in milliseconds since epoch.

requestedDataPoints

int

No

Desired number of data points returned per series.

maxDataPoints

Int

No

Upper bound on number of data points returned per series

maxTotalDataPoints

Int

No

Upper bound on sum total number of data points returned across all series.

desiredQuantizationInSec

Int

No

Desired granularity of temporal quantization (DAVID A TODO LINK), 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

Parameter

Type

Required

Description

query

String

Yes

The actual metrics search expression.

rowId

String

Yes

Name or alias for this “row” of the query.

 

Status codes

Code

Text

Description

200

Success

The query has been successfully executed.

400

Bad Request

Generic request error by the client.

415

Unsupported Media Type

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

Parameter

Type

Description

response

[MetricsErrorsOrResults]

Results (or error) for each row-query.

queryInfo

MetricsQueryInfo

Information about the original user query.

 

MetricsQueryInfo object

Parameter

Type

Description

startTime

long

Start of the query time range, in milliseconds since epoch.

endTime

long

End of the query time range, in milliseconds since epoch.

desiredQuantizationInSecs

int

Original user-supplied desired granularity of temporal quantization (if supplied).

actualQuantizationInSecs

int

Actual granularity of temporal quantization used by the back-end for query.

 

MetricsDatapointsError object

(extends MetricsErrorsOrResults)

Parameter

Type

Description

rowId

String

Name or alias for this “row” of the query.

messageType

String

Error type.

message

String

Error message.

 

MetricsDataPointsResult object

(extends MetricsErrorsOrResults)

Parameter

Type

Description

rowId

String

Name or alias for this “row” of the query.

results

[MetricsRowResult]

Actual retrieved and computed values for series returned by this row’s query.

 

 

MetricsRowResult

Parameter

Type

Description

metric

MetricDef

Full metric definition for this result.

datapoints

MetricsDataPoints

The actual results.

 

MetricDef

Parameter

Type

Description

dimensions

[MetricDim]

Identifying dimensions for this metric.

algoId

long

Internal identifier for the outlier detection algorithm used in these results.

MetricDim

Parameter

Type

Description

key

string

Key name for this dimension.

value

string

Associated value for this key.

 

MetricsDataPoints

Parameter

Type

Description

timestamp

[long]

Timestamps (milliseconds since epoch) for each data point.

value

[float]

Actual numerical values for reach data point.

outlierParams

 

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