NRQL Lookups API

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
`create`	`POST /v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME`	Upload a new table.
`update`	`PUT /v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME`	Replace an existing table.
`read`	`GET /v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME`	Download a table that was previously uploaded.
`delete`	`DELETE /v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME`	Delete the given table.
`list`	`GET /v1/accounts/YOUR_ACCOUNT_ID`	List the tables previously updated for this account.

The variables required in the above NRQL Lookups API endpoints are defined below.

Variable	Type	Description
`YOUR_ACCOUNT_ID`	`number`	The account to which the table belongs
`TABLE_NAME`	`string`	A name for the stored table. Table names must comply with the custom event type standards: Maximum length: 255 Can be a combination of alphanumeric characters, underscores, and colons.

Variable

Type

Description

YOUR_ACCOUNT_ID

number

The account to which the table belongs

TABLE_NAME

string

A name for the stored table. Table names must comply with the custom event type standards:

Maximum length: 255
Can be a combination of alphanumeric characters, underscores, and colons.

Authentication

Your serves to authenticate your request to the NRQL Lookups API and needs to be passed as an HTTP header.

Header	Supported values
`Api-Key`	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
`includeTable`	`boolean`	`false`	Indicates whether to include the table value in the response.

HTTP Headers

When creating your HTTP headers, use these guidelines:

Header	Supported values
`Content-Type`	`multipart/form-data` `application/json`
`Accept`	`application/json`

Request Body

The data you send in your request body can either be multipart/form-data or application/json.

Supported Fields

You can provide the following fields in your create and update requests when sending multipart/form-data content:

Field	Value Type	Required	Description
`table`	CSV file	Yes	Multipart form-data part that contains the CSV content. Our CSV parsing logic is outlined in detail here.
`description`	`string`	No	Second multipart form-data part that contains a description of the table.

Example payload

--__X_BOUNDARY__
Content-Disposition: form-data; name="table"; filename="sample.csv"
Content-Type: text/csv

id,name,intvalue,floatvalue,boolvalue
'1,abc,27,2.7,true
'2,def,2622,26.22,false
'2a,"g,hi",1234,43.21,false
--__X_BOUNDARY__--
Content-Disposition: form-data; name="description"

A description of the table
--__X_BOUNDARY__--

Supported Fields

You can provide the following fields in your create and update when sending application/json content:

Field

Value Type

Required

Description

table

JSON

Yes

`headers`	An array of `string` values representing the column names of the table
`rows`	An array of arrays, representing the values of the table. All values must be a `string`, `number`, or `boolean` values. (Complex JSON objects are not allowed.)

description

string

A detailed description of the table

Example payload

{
  "table": {
    "headers": ["id", "name", "text", "intvalue", "floatvalue", "boolvalue"],
    "rows": [
      ["1", "abc", 27, 2.7, true],
      ["2", "def", 2622, 26.22, false],
      ["2a", "d,ef", 1234, 43.21, false]
    ]
  },
  "description": "This is a description."
}

Response Body

If the request is successful, the response JSON payload can include the following fields:

Field

Value Type

Description

accountId

number

The account to which the table belongs. This will match the account value in the path.

name

string

A name for the stored table. This will match the name value in the path.

description

string

A detailed description of the table

guid

string

The guid assigned to the table upon creation.

size

number

Size of the table as a CSV string.

rows

number

The number of rows in the table (excluding the header row)

updatedBy

string

The username/email address of the last user that created or last updated this table.

updatedAt

string

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)

table

JSON object literal

`headers`	An array of `string` values representing the column names of the table
`rows`	An array of arrays, representing the values of the table.

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

To create a new lookup table, we can send a POST request to the create endpoint with a JSON payload describing the lookup table.

Here's an example curl command:

bash

$curl -X "POST" "https://nrql-lookup.service.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME" \
>      -H 'Content-Type: application/json' \
>      -H 'Api-Key: YOUR_USER_KEY'\
>      -d $'{
$  "table": {
$  "headers": ["id", "name", "intvalue", "floatvalue", "boolvalue"],
$  "rows": [
$      ["1", "abc", 27, 2.7, true],
$      ["2", "def", 2622, 26.22, false]
$  ]
$  },
$  "description": "This is a description."
$  }'

To replace an existing lookup table, we can send a PUT request to the update endpoint with a multipart/form-data request body containing the new table.

bash

$curl -X "PUT" "https://nrql-lookup.service.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME" \
>   -H 'Api-Key: YOUR_USER_KEY'\
>   -H 'Content-Type: multipart/form-data; charset=utf-8; boundary=__X_PAW_BOUNDARY__' \
>   -F "table=id,name,description,intvalue,floatvalue,boolvalue
$      1,abc,desc1,27,2.7,true
$      2,def,desc2,2622,26.22,false
$      " \
>   -F "description=This is a description."

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
`includeTable`	`boolean`	`false`	Indicates whether to include the table value in the response. Ignored when the content type is `text/csv`.

HTTP Headers

When creating your HTTP headers, use these guidelines:

Header	Supported values
`Accept`	`application/json` `text/csv`

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

To download a table that was previously uploaded, we can send a GET request to the update endpoint.

Here's an example curl command:

bash

$curl "https://nrql-lookup.service.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME" \
>     -H 'Accept: text/csv' \
>     -H 'Api-Key: YOUR_USER_KEY'

Here's an example text/csv response:

id,name,intvalue,floatvalue,boolvalue
'1,abc,27,2.7,true
'2,def,2622,26.22,false
'2a,"g,hi",1234,43.21,false

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
`includeTable`	`boolean`	`false`	Indicates whether to include the table value in the response.

HTTP Headers

When creating your HTTP headers, use these guidelines:

Header	Supported values
`Accept`	`application/json`

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

To delete a table that was previously uploaded, we can send a DELETE request to the delete endpoint.

Here's an example curl command:

bash

$curl -X "DELETE" "https://nrql-lookup.service.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME" \
>     -H 'Accept: application/json' \
>     -H 'Api-Key: YOUR_USER_KEY'\

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
`Accept`	`application/json`

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
`accountId`	`number`	The account to which the table belongs. This will match the account value in the path.
`name`	`string`	A name for the stored table. This will match the name value in the path.
`description`	`string`	A more detailed description of the table
`guid`	`string`	The guid assigned to the table upon creation.
`size`	`number`	The size of the table as a CSV string.
`rows`	`number`	The number of rows in the table (excluding the header row)
`updateBy`	`string`	The username/email address of the last user that updated this table.
`updatedAt`	`string`	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

To list the tables for an account, we can send a GET request to the list endpoint.

Here's an example curl command:

bash

$curl "https://nrql-lookup.service.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID" \
>     -H 'Accept: text/csv' \
>     -H 'Api-Key: YOUR_USER_KEY'

Here's an 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"
  },
  {
    "accountId": YOUR_ACCOUNT_ID,
    "name": "sample2",
    "guid": "eac37270-7c02-4ca9-b178-8be5748b5b09",
    "size": 4096
    "rows": 2000
    "updatedBy": "janedoe@example.com"
    "updatedAt": "2023-02-14T13:30:21.100Z"
  }
]

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
}

Before you start.css-21sua1{background:none;border:none;width:0;padding:0;}

HTTP endpoints

Base URL

Endpoints

Authentication

Create/Update a Table

HTTP Endpoints

Create

Update

Request Query Parameters

HTTP Headers

Request Body

Request with application/json

Response Body

Example Response JSON payload

Example Requests

Create a new table

Update an existing table

Read a Table

HTTP Endpoint

Request Query Parameters

HTTP Headers

Response Body

Response with application/json type

Response with text/csv type

Example Requests

Download an existing table

Delete a Table

HTTP Endpoint

Important

Request Query Parameters

HTTP Headers

Response Body

Example Requests

Delete an existing table

List Tables

HTTP Endpoint

HTTP Headers

Response Body

Example Request

Listing tables updated for an account

Error Messaging

Before you start

Response with `application/json` type

Response with `text/csv` type