Use the NRQL Lookups API to create and manage lookup tables.
Before you start
The NRQL Lookups API is a REST API that allows you to manage lookup tables programmatically. As another option you can also manage lookup tables through our UI.
HTTP endpoints
Base URL
Use the base URL that's applicable for your New Relic account in your API calls.
United States (US) endpoint:
https://nrql-lookup.service.newrelic.com
European Union (EU) endpoint:
https://nrql-lookup.service.eu.newrelic.com
Endpoints
Method | Endpoint | Description |
---|---|---|
| Upload a new table. | |
| Replace an existing table. | |
| Download a table that was previously uploaded. | |
| Delete the given table. | |
| List the tables previously updated for this account. |
The variables required in the above NRQL Lookups API endpoints are defined below.
Variable | Type | Description |
---|---|---|
|
| The account to which the table belongs |
|
| A name for the stored table. Table names must comply with the custom event type standards:
|
Authentication
Your serves to authenticate your request to the NRQL Lookups API and needs to be passed as an HTTP header.
Header | Supported values |
---|---|
| A New Relic . |
Create/Update a Table
HTTP Endpoints
Create
POST /v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME
Used to upload a new table. The table cannot already exist. If it does, this call will result in a 400 Bad Request
response.
Update
PUT /v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME
Used to replace an existing table. If the table does not exist this call will result in a 404 Not Found
response.
Request Query Parameters
Name | Type | Default | Description |
---|---|---|---|
|
|
| Indicates whether to include the table value in the response. |
HTTP Headers
When creating your HTTP headers, use these guidelines:
Header | Supported values |
---|---|
|
|
|
|
Request Body
The data you send in your request body can either be multipart/form-data
or application/json
.
Response Body
If the request is successful, the response JSON payload can include the following fields:
Field | Value Type | Description | ||||
---|---|---|---|---|---|---|
|
| The account to which the table belongs. This will match the account value in the path. | ||||
|
| A name for the stored table. This will match the name value in the path. | ||||
|
| A detailed description of the table | ||||
|
| The guid assigned to the table upon creation. | ||||
|
| Size of the table as a CSV string. | ||||
|
| The number of rows in the table (excluding the header row) | ||||
|
| The username/email address of the last user that created or last updated this table. | ||||
|
| The timestamp of when the table was created or last updated. This will reflect the last updated timestamp of the S3 object. The value will be a standard ISO 8601 date time string (ex. 2023-02-13T19:49:28.023Z) | ||||
|
|
|
Example Response JSON payload
{ "accountId": YOUR_ACCOUNT_ID, "name": "sample", "guid": "eac37270-7c02-4ca9-b178-8be5748b5b09", "size": 120 "rows": 3 "updatedBy": "jondoe@example.com" "updatedAt": "2023-02-13T19:49:28.023Z", "table": { "headers": [ "id", "name", "description", "intvalue", "floatvalue", "boolvalue" ], "rows": [ [1, "abc", 27, 2.7, true], [2, "def", 2622, 26.22, false], ["2a", "d,ef", 1234, 43.21, false] ] }}
Example Requests
Read a Table
HTTP Endpoint
GET /v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME
Used to download a table that was previously uploaded. If the table does not exist this call will result in a 404 Not Found
response. This endpoint has no request payload.
Request Query Parameters
Name | Type | Default | Description |
---|---|---|---|
|
|
| Indicates whether to include the table value in the response. Ignored when the content type is |
HTTP Headers
When creating your HTTP headers, use these guidelines:
Header | Supported values |
---|---|
|
|
Response Body
If the request is successful, the response can either be of type application/json
or text/csv
.
Response with application/json
type
The response will be the same as the create/update response payload.
Response with text/csv
type
The response will contain the table in CSV format.
Example Requests
Delete a Table
HTTP Endpoint
DELETE /v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME
Used to delete the given table. If the table does not exist this call will result in a 404 Not Found
response. This endpoint has no request payload.
Important
Deleted tables are not recoverable.
Request Query Parameters
Name | Type | Default | Description |
---|---|---|---|
|
|
| Indicates whether to include the table value in the response. |
HTTP Headers
When creating your HTTP headers, use these guidelines:
Header | Supported values |
---|---|
|
|
Response Body
If the request is successful and the Accept
header is set to application/json
, the response body will be the same as the create/update response payload.
Example Requests
List Tables
HTTP Endpoint
GET /v1/accounts/YOUR_ACCOUNT_ID
Lists the tables previously updated for this account. This endpoint has no request payload.
HTTP Headers
When creating your HTTP headers, use these guidelines:
Header | Supported values |
---|---|
|
|
Response Body
If the request is successful, the response JSON payload will consist of an array of table summaries. Each table summary can include the fields below.
Field | Value Type | Description |
---|---|---|
|
| The account to which the table belongs. This will match the account value in the path. |
|
| A name for the stored table. This will match the name value in the path. |
|
| A more detailed description of the table |
|
| The guid assigned to the table upon creation. |
|
| The size of the table as a CSV string. |
|
| The number of rows in the table (excluding the header row) |
|
| The username/email address of the last user that updated this table. |
|
| The timestamp of when the table was created or last updated. This will reflect the last updated timestamp of the S3 object. The value will be a standard ISO 8601 date time string (ex. 2023-02-13T19:49:28.023Z) |
Example Request
Error Messaging
If a request is unsuccessful, the error response payload will be in the format below.
{ "code": HTTP_STATUS_CODE(same as status header), "message": ERROR_MESSAGE}