SignalFx Developers Guide

Developer Home

Product Docs


Retrieve Custom Events API

API for retrieving custom events

Retrieve Custom Events Using Query

Retrieves custom events specified by search criteria

get /event

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use, SignalFx interprets the endpoint as pointing to the us0 realm.


Retrieves one or more custom events from SignalFx, based on query parameters you specify:

  • The query query parameter specifies name- and value-based search criteria.
  • The time query parameters specify a time window from which to retrieve datapoints
  • The offset parameter specifies the point in the query results at which the API should start sending event data.
  • The limit parameter specifies the number of results to send.

The API combines the query results and the time window with a logical "and"; that is, the result set contains custom events that match the query parameter criteria and have a timestamp that's within the window specified by the time query parameters. From the result set, the API returns a limit number custom events starting at the offset in the result set.
The orderBy parameter controls the order of the results you receive.
If you don't specify any query parameters, the API sends you all of the custom events it has for your organization, in an indeterminate order.
This API doesn't take a request body

query Parameters

Search criteria that specifies the custom events that you want the API to return. You can search for any of the event properties.
Search criteria have the following rules:

  • To search for specific values of a property, specify <name>:<value>. If <value> contains blanks, surround it with double quotes.

  • To search for names or values using wildcards, use * as the wildcard character. For example, to search for all values of the region dimension, use region:*.

  • A single property name and value (or wildcards) make up a predicate that implicitly returns a boolean.

  • Join predicates with the NOT, AND, and OR boolean operators.

  • Use parentheses '(' and ')' to change the evaluation order.

    For example, to retrieve all custom events that have an eventType prefixed with myCompany and have the dimension region:emea, use `query="eventType:myCompany* AND region:emea".

integer <int64>
Example: 1557523830000

Start of the time window from which the API should retrieve custom events. Specify the value in Unix time, and remember to correct for your time zone.
If the value is negative, the API interprets it as an offset before the current server time (UTC).
If you specify from but not to, the time window extends to the current server time.

integer <int64>
Example: 1557696630000

End of the time window from which the API should retrieve custom events. Specify the value in Unix time and remember to correct for your time zone.
If the value is negative, the API interprets it as an offset before the current server time (UTC).
If you specify to but not from, the time window extends from the earliest event to the value of to.


The field on which the API should sort the query results. The value can be any custom event property, including metadata

integer <int32>

The index in the query result set at which the API should start sending results to you. For example, 0 is first result in the set, and 10 is the 11th result.

integer <int32>

The number of custom events to return. If you specify -1, the API returns 1000 results. The value of limit is an upper boundary on the number of results; the API may return less depending on the other query parameters

header Parameters

User access token (referred to as a User API Access Token in the web UI) that has authorization to retrieve custom events.



Successful custom event retrieval request

Response Schema: application/json

A category that describes the custom event, in the form of one of the allowed enumerated types:

  • USER_DEFINED: The default for custom events
  • ALERT: Used by SignalFx to mark an event generated by a detector.
  • AUDIT: Used by third-party integrations
  • JOB: Event generated by a SignalFx or third-party background job
  • COLLECTD: Generated by the SignalFx CollectD integration
  • SERVICE_DISCOVERY: Generated by third-party integrations
  • EXCEPTION: A software exception occurred

A name for the custom event. Use this name to find the event in other API calls or in the web UI.


A list of key-value pairs that specify dimension names and values to associate with the event. SignalFx assumes that each value of eventType you send is associated with a specific set of dimension names and values.


A list of key-value pairs that specify properties of the specified event.

integer <int64>

The date and time of the event in Unix time UTC-relative

Response samples

Expand all Collapse all
  • {

© Copyright 2019 SignalFx.

Third-party license information