As of April 12, 2021, we are upgrading Insights to an improved web and mobile experience! All of your Insights URLs will be redirected automatically to the corresponding dashboards in New Relic One. For more details about this migration and how you can easily plan for this transition, see our Explorers Hub post.
The New Relic Event API is one way to report custom events to New Relic. The Event API lets you send custom event data to your New Relic account with a POST command. These events are then queryable and chartable using NRQL.
To use APIs and the rest of our observability platform, join the New Relic family! Sign up to create your free account in only a few seconds. Then ingest up to 100GB of data for free each month. Forever.
- Learn about all options for reporting custom events.
- For details about how event data is retained, see Event data retention.
- For how to add attributes to existing events, see Add custom attributes.
- Check out New Relic University’s tutorial Adding custom events with the Event API (aka the Insights API). Or, go directly to the full online course Custom data.
For Event API limits and restricted attributes, see Limits.
Ensure outbound connectivity on TCP port 443 is allowed to the CIDR range that matches your region.
The preferred configuration method is to use the DNS name
The Event API is an asynchronous endpoint. This allows you to send a very large volume of POSTS, reliably, with very low response latency.
If your account hosts data in the EU data center, ensure you are using the proper API endpoints for EU region accounts.
To send a custom event to your New Relic account:
- Register an Insert API key.
- Before creating custom events or attributes, review New Relic's list of reserved terms used by NRQL.
- Generate JSON for the event by instrumenting your application, querying an API, or some other method.
- Submit a compressed JSON payload (for example,
deflate) to the HTTPS endpoint using curl in a POST request.
- Recommendation: Set up NRQL alert conditions to notify you when parsing errors occur.
This method will send the events directly into your account, where they will be accessible from any NRQL interface or with the Query API.
The Event API limits the size, rate, and characters allowed in custom events. Also, like other events available in NRQL, custom events cannot be updated or deleted after they are created. If you have problems with your custom event, follow the troubleshooting procedures or create a new custom event.
You must have the correct user permissions to register Insert API keys.
Insert API keys are generated for an account. They aren't associated with a specific user. Anyone in the account with access to the Insert API key can use it.
You submit multiple event types under a single Insert API key. However, to help ensure security, we recommend that you use different keys for different applications or data sources.
To register an Insert API key:
- From one.newrelic.com, click the account dropdown and then click Account settings.
- Click API keys and click Insights insert keys.
- Next to the Insert keys heading, select the symbol and follow the instructions.
The Insert key page lists the curl command necessary to add event data for the key.
For security reasons, the Insert API key cannot be altered or read using the API. To change or read a key, use the New Relic UI.
The Event API accepts specific formats for attributes included in the payload. Only float or string values are allowed.
Data submitted to the Event API uses a compressed JSON format in a simple HTTPS POST request. The Insert key page in the Insights UI automatically generates a sample curl query for you to use as a template. This example uses
gzip, but you can also use
Always use compression with every payload. This allows you to send more data, and it saves resources during parsing.
Before generating your HTTP request, make sure it is properly formatted, including:
X-Insert-Keycontains the correct Insert API key.
- The request uses POST only. The API does not accept PUT and GET requests.
The API supports HTTP/1.1 persistent connections. This is helpful to manage client-side performance under heavy event loads.
The Event API follows a two-step process to process requests:
- The Event API synchronously acknowledges or rejects the request based on validation of the headers and payload size.
- The Event API asynchronously parses the payload after a successful HTTP response is provided to the client. This may generate an error due to missing or malformed data. These are classified as submission errors or parsing errors.
All successful submissions receive a
200 response, regardless of any data errors that may exist within the payload. The response includes a
uuid, which is a unique ID created for each request. The
uuid also appears in any error events created for the request.
Other potential issues:
- 10-second timeout: API calls exceeding 10 seconds will time out.
- Large payloads: Payloads exceeding 100 KB may see increased response times.
Recommendation: In addition to checking for a success message, use the Insights data explorer to ensure your events are reporting correctly and to generate queries.
NrIntegrationError event allows you to query and set alerts on custom data being sent to your New Relic account. Recommendation: To have New Relic Alerts notify you about parsing errors, create a NRQL condition for
NrIntegrationError. Use this example NRQL query:
SELECT message FROM NrIntegrationError WHERE newRelicFeature = 'Event API' AND category = 'EventApiException'
The timestamp when the request was received. The
Do not use a decimal for the timestamp. If a decimal is used, the attribute will default to the timestamp when the custom event was created.
The name of the feature experiencing errors. For all custom event parsing errors, this will be
The first six characters of the Insert API key used for the request that generated an error.
The category of the error. For custom events, this is
Contents of the error message.
The error's name. For custom events, this is always
One of the event types that generated the error, when available.
To find data sent via the Event API (and from integrations that use this API), you can query it. For example, to query a custom event using NRQL, you would run:
SELECT * FROM YOUR_CUSTOM_EVENT
For more on how to query, see Query data.
The Event API has a rate limit of 100,000 HTTP requests (POSTs) per minute, per account. (Note that this is not a limit on the number of events per minute; only on the number of POSTs per minute.)
This limit helps ensure that large traffic spikes in accounts across our multi-tenant platform do not negatively affect how the service performs for you.
If your API usage exceeds 100k POSTs in a 1-minute window, we will reject subsequent API requests with a 429 response code for the remainder of the 1-minute window. At the end of the 1-minute window, the counter will be reset and allow traffic to resume.
This limit is intended to be an upper threshold that you shouldn't hit under normal scenarios. If you have a high number of 429 responses, consider using the API less. If you are expecting a higher-than-normal activity level in the near future and want to prepare for that, contact technical support.
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's data security and licenses documentation.