New Relic API Getting Started: Quickstart and First Request (2026)

Getting started overview

To begin using the New Relic API, the initial steps involve setting up an account, understanding the different types of API keys, and executing a foundational request. New Relic offers various APIs, including the NerdGraph API (a GraphQL endpoint for querying and configuring data) and several REST APIs for specific functions like data ingestion, insights, and configuration management. This guide focuses on the general process applicable across these APIs, emphasizing key acquisition and a basic API interaction.

The New Relic platform provides full-stack observability, enabling teams to monitor applications, infrastructure, and user experiences. The APIs extend this capability, allowing programmatic interaction with the platform's data and features. For instance, developers can automate the creation of dashboards, integrate alert systems with external tools, or push custom metrics into New Relic for unified monitoring. Understanding the distinction between API key types—Ingest, Query, and User—is crucial for secure and effective API usage. Each key type grants specific permissions, aligning with the principle of least privilege.

Before making any API calls, ensure you have an active New Relic account. The free tier provides 100 GB of free data ingest per month and one free full user, allowing developers to explore the platform's capabilities without an initial financial commitment. For more details on account types and usage, consult the official New Relic pricing page.

Here's a quick reference for the getting started process:

Create an account and get keys

The foundation of using the New Relic API is establishing an account and securing the necessary authentication credentials. New Relic employs different types of API keys, each designed for specific purposes and access levels, which is a common practice for API security to implement the principle of least privilege.

1. Sign Up for a New Relic Account:

   Navigate to the New Relic homepage and initiate the signup process. You can start with the free tier, which offers 100 GB of free data ingest per month and one full user, sufficient for initial exploration and development. During signup, you'll provide basic information and set up your organization.

2. Locate Your Account ID:

   Your New Relic account ID is a numerical identifier crucial for many API calls, especially when querying data via NerdGraph. You can find your account ID in the New Relic One UI by navigating to Account settings or by checking the URL when logged in (it's often part of the path, e.g., one.newrelic.com/nr1-core/permanent-redirect/YOUR_ACCOUNT_ID/...).

3. Generate API Keys:

   New Relic distinguishes between several types of API keys:

   • Ingest API Key: Used for sending data to New Relic, such as custom events, logs, or metrics. This key grants permissions to write data to your account.

   • Query API Key: Used for retrieving data from New Relic via the NerdGraph API or Insights API. This key grants read-only access to your account's data.

   • User API Key (or Personal API Key): Used for administrative tasks and configuration changes, often with broader permissions. These keys are tied to a specific user's permissions within New Relic.

   To generate these keys:

   1. Log in to New Relic One.
   2. In the left-hand navigation, go to API keys.
   3. Click on Create a key or locate existing keys. Select the appropriate key type (Ingest, Query, or User) based on your intended API interaction.
   4. Provide a descriptive name for your key to easily identify its purpose later.
   5. Copy the generated key immediately, as it may not be retrievable again for security reasons. Store it securely.

For detailed instructions on managing API keys, refer to the New Relic API key documentation.

Your first request

Once you have your Account ID and the necessary API keys, you can make your first API request. This example will demonstrate how to send a custom event using the Telemetry Data Platform's Event API, which is a common way to ingest custom data into New Relic.

Example: Sending a Custom Event (Telemetry Data Platform API)

This example uses curl, a command-line tool, for simplicity. You'll need an Ingest API Key for this operation.

Endpoint: The New Relic Telemetry Data Platform Event API endpoint varies based on your New Relic region. For the US region, it's typically https://insights-collector.newrelic.com/v1/accounts/{YOUR_ACCOUNT_ID}/events. Always confirm the correct endpoint for your region in the New Relic Event API documentation.

Request Structure:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Api-Key: YOUR_INGEST_API_KEY" \
  "https://insights-collector.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/events" \
  -d "[
        {
          \"eventType\": \"MyCustomEvent\",
          \"attribute1\": \"value1\",
          \"attribute2\": 123.45,
          \"timestamp\": $(($(date +%s%N)/1000000)) # Current timestamp in milliseconds
        }
      ]"

Replace these placeholders:

• YOUR_INGEST_API_KEY: Your actual Ingest API Key.
• YOUR_ACCOUNT_ID: Your New Relic account ID.
• eventType: A descriptive name for your custom event (e.g., DeploymentStatus, OrderProcessed).
• attribute1, attribute2: Custom attributes relevant to your event. You can include any number of key-value pairs.

Explanation:

• -X POST: Specifies the HTTP POST method, used for sending data.
• -H "Content-Type: application/json": Sets the content type of the request body.
• -H "Api-Key: YOUR_INGEST_API_KEY": Passes your Ingest API Key in the Api-Key header for authentication.
• The URL targets the Event API endpoint for your specific account.
• -d "[...]": Contains the JSON payload, which is an array of event objects. Each object represents a single event with an eventType and any custom attributes. The timestamp is optional but recommended for accurate time-series data.

After executing this curl command, you should receive a 202 Accepted HTTP status code, indicating that your event has been successfully received for processing. You can then navigate to the New Relic One UI, go to the NRQL query explorer, and query for your custom event (e.g., SELECT * FROM MyCustomEvent SINCE 1 hour ago) to verify that the data has been ingested.

Common next steps

After successfully making your first API call, consider these next steps to further integrate with New Relic and leverage its observability features:

1. Explore Other APIs:

   • NerdGraph API (GraphQL): For querying existing data (metrics, events, logs, traces) and managing configurations (alerts, dashboards, synthetic monitors). This is the primary API for programmatic interaction with much of the New Relic platform. Consult the NerdGraph API introduction.
   • Alerts API: Automate the creation and management of alert policies and conditions.
   • Synthetics API: Programmatically manage synthetic monitors to check application availability and performance from various global locations.

2. Utilize SDKs and Integrations:

   New Relic provides official SDKs for popular languages like Java, Node.js, Python, .NET, PHP, Ruby, and Go. These SDKs simplify data ingestion and agent configuration. Additionally, explore existing New Relic integrations for popular cloud providers and services.

3. Build Custom Dashboards and Alerts:

   Use the data you're sending via the API to create custom dashboards in New Relic One. Configure alerts based on specific thresholds or anomalies in your custom metrics or events. This allows proactive monitoring and notification of issues.

4. Implement Advanced Security:

   Beyond basic API keys, consider implementing more advanced security practices, such as rotating API keys regularly, restricting key permissions, and using environment variables for sensitive credentials instead of hardcoding them. For production environments, investigate secure credential management systems. The AWS Secrets Manager documentation provides a good example of such a system.

5. Monitor API Usage and Errors:

   Keep an eye on your API usage within the New Relic UI and monitor for any API-related errors. This helps ensure that your integrations are functioning correctly and that you are not exceeding any rate limits or data ingest quotas.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps for the Event API example:

• Check API Key Validity:

  • Ensure you are using the correct type of API key. For sending events, you must use an Ingest API Key. A Query API Key will result in an authentication error.
  • Verify that the API key is correctly copied and pasted without extra spaces or characters.
  • Confirm the API key has not been revoked or expired (though keys typically do not expire unless explicitly set).

• Verify Account ID and Endpoint:

  • Double-check that your YOUR_ACCOUNT_ID in the URL is correct.
  • Ensure you are using the correct New Relic API endpoint for your region (e.g., US, EU, APAC). Using the wrong region's endpoint will lead to connection issues or data not appearing.

• Examine JSON Payload Format:

  • The JSON payload must be valid. Use a JSON linter or validator to check for syntax errors (e.g., missing commas, unescaped quotes, incorrect brackets).
  • Ensure the eventType field is present and correctly formatted.
  • The payload should be an array of event objects, even if sending only one event.

• Review HTTP Status Codes and Error Messages:

  • 401 Unauthorized: Typically indicates an incorrect or missing API key.
  • 403 Forbidden: The API key might lack the necessary permissions for the requested action.
  • 400 Bad Request: Often points to an issue with the JSON payload format or invalid parameters.
  • 404 Not Found: Usually means the endpoint URL is incorrect or the resource doesn't exist.
  • 202 Accepted: Indicates success; the event has been queued. If data doesn't appear, check the event type and attributes in New Relic One's NRQL explorer.

• Check Network Connectivity and Firewalls:

  • Ensure your machine has internet access and that no local firewall rules are blocking outbound connections to New Relic's API endpoints.

• Consult New Relic Documentation:

  The New Relic API documentation is an extensive resource for specific error codes, common issues, and detailed API specifications.