--- title: NRQL Lookups API source: https://docs.newrelic.com/docs/apis/lookups-service-api/lookups-service-api --- Use the NRQL Lookups API to create and manage [lookup tables](https://docs.newrelic.com/docs/logs/ui-data/lookup-tables-ui/#overview). ## 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](https://docs.newrelic.com/docs/logs/ui-data/lookup-tables-ui/#lookup-ui). ## HTTP endpoints [#http-endpoints] ### Base URL Use the base URL that's applicable for your New Relic account in your API calls. United States (US) endpoint (default): ``` https://nrql-lookup.service.newrelic.com ``` [European Union](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/introduction-eu-region-data-center) (EU) endpoint: ``` https://nrql-lookup.service.eu.newrelic.com ``` [Japan](https://docs.newrelic.com/docs/accounts/accounts-billing/account-setup/choose-your-data-center) (JP) endpoint: ``` https://nrql-lookup.service.jp.newrelic.com ``` ### Endpoints | Method | Endpoint | Description | | ------------------------------ | ------------------------------------------------ | ---------------------------------------------------- | | [`create`](#create-and-update) | `POST /v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME` | Upload a new table. | | [`update`](#create-and-update) | `PUT /v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME` | Replace an existing table. | | [`read`](#read) | `GET /v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME` | Download a table that was previously uploaded. | | [`delete`](#delete) | `DELETE /v1/accounts/YOUR_ACCOUNT_ID/TABLE_NAME` | Delete the given table. | | [`list`](#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](https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/data-requirements-limits-custom-event-data/#general): - Maximum length: 255 - Can be a combination of alphanumeric characters, underscores, and colons. | ## Authentication Your user key 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 user key. | ## Create/Update a Table [#create-and-update] ### HTTP Endpoints [#create-and-update-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 [#create-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 [#create-request-body] The data you send in your request body can either be `multipart/form-data` or `application/json`. **Request with multipart/form-data** #### 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](https://docs.newrelic.com/docs/logs/ui-data/lookup-tables-ui/#valuetypes). | | `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__-- ``` ```` **Request with application/json** #### 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` | No | A detailed description of the table | #### Example payload ````json { "table": { "headers": [ "id", "name", "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 [#create-update-response] 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 ```json { "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 **Create a new table** 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." }' ``` ```` **Update an existing table** 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 [#read] ### HTTP Endpoint [#read-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 [#read-headers] When creating your HTTP headers, use these guidelines: | Header | Supported values | | -------- | --------------------------------- | | `Accept` | - `application/json` - `text/csv` | ### Response Body [#read-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](#create-update-response). #### Response with `text/csv` type The response will contain the table in CSV format. ### Example Requests [#read-example-requests] **Download an existing table** 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: ```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 ``` ## Delete a Table [#delete] ### HTTP Endpoint [#delete-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 [#delete-headers] When creating your HTTP headers, use these guidelines: | Header | Supported values | | -------- | -------------------- | | `Accept` | - `application/json` | ### Response Body [#delete-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](#create-update-response). ### Example Requests [#delete-example-request] **Delete an existing table** 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 [#list] ### HTTP Endpoint [#list-endpoint] `GET /v1/accounts/YOUR_ACCOUNT_ID` Lists the tables previously updated for this account. This endpoint has no request payload. ### HTTP Headers [#list-headers] When creating your HTTP headers, use these guidelines: | Header | Supported values | | -------- | -------------------- | | `Accept` | - `application/json` | ### Response Body [#list-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 [#list-example-request] **Listing tables updated for an account** 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: ```json [ { "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 [#error-messaging] If a request is unsuccessful, the error response payload will be in the format below. ```json { "code": HTTP_STATUS_CODE(same as status header), "message": ERROR_MESSAGE } ```