Try it free

Upload lookup data

  • Latest Dynatrace
  • Reference
  • Published Oct 13, 2026

Upload lookup data in Dynatrace with the Grail Resource Store API and save or replace a tabular file after parsing the content with DPL.

POSTSaaShttps://{your-environment-id}.apps.dynatrace.com/v1/files/tabular/lookup:upload

Overview

Upload lookup data

Upload lookup data and store it as a new tabular file in the Grail Resource Store or replace an existing one. The request body needs to be submitted as multipart/form-data with the following parts:

  • request: containing the request parameters (see below) in JSON format
  • content: containing the lookup data in text format

The uploaded data is parsed using the Dynatrace Pattern Language (DPL). For examples, see the Dynatrace Documentation.

Request parameters

  • filePath (required) - The fully qualified file path of the tabular file to store the lookup data in Grail. Example: /lookups/mydata. The following constraints apply:

    • must only contain alphanumeric characters [a-zA-Z0-9], -, _, ., /
    • must start with /lookups
    • must end with [a-zA-Z0-9]
    • must contain at least two / characters
    • between any two consecutive / characters there must be at least one [a-zA-Z0-9] character
    • can be up to 500 characters long

  • overwrite - If false and the file already exists, the upload fails. Set to true to allow overwriting existing files. Default: false

  • displayName - An optional name for the file. The length is limited to 500 characters.

  • description - An optional description for the file. The length is limited to 500 characters.

  • parsePattern (required) - The DPL pattern to parse the uploaded data. Every pattern match produces a record. Example: LD:id ',' LD:value.

  • skippedRecords - The number of initial records to discard. Can be used to skip header rows. Default: 0

  • lookupField (required) - The name of the lookup field whose value identifies a record in the lookup data. The uniqueness of the values is ensured by deduplicating records during
    upload, if necessary.

  • timezone - The timezone for parsing time and date fields. The list of valid input values matches that of the IANA Time Zone Database (TZDB). Example: UTC.

  • locale - The locale for parsing locale-specific day and month names. The input values take the ISO-639 Language code with an optional ISO-3166 country code appended to it with an underscore. Example: en_US.

  • autoFlatten - Set to true to extract nested fields to the root level when the specified DPL pattern results in a single record-type field. Default: true

  • dt.cost.costcenter - Can be used to assign usage to a Cost Center.

  • dt.cost.product - Can be used to assign usage to a Product or Application Id.

Authentication

To execute this request, you need a platform token or OAuth access token with storage:files:write scope. To learn how to obtain and use it, see Tokens and authentication.

Parameters

ParameterTypeDescriptionInRequired
bodyResourceUploadRequestEnvelope

Multipart request containing JSON metadata and file content.

bodyOptional

Request body objects

The ResourceUploadRequestEnvelope object

Multipart request containing JSON metadata and file content.

ElementTypeDescriptionRequired
contentstring-Required
requestResourceUploadRequest

The JSON metadata for the upload request.

Required

The ResourceUploadRequest object

The JSON metadata for the upload request.

ElementTypeDescriptionRequired
autoFlattenboolean

Set to true to extract nested fields to the root level when the specified DPL pattern results in a single record-type field.

Optional
descriptionstring

An optional description for the file.

Optional
displayNamestring

An optional name for the file.

Optional
dt.cost.costcenterstring

Can be used to assign usage to a Cost Center.

Optional
dt.cost.productstring

Can be used to assign usage to a Product or Application Id.

Optional
filePathstring

The fully qualified file path of the tabular file to store the lookup data in Grail.

Required
localestring

The locale for parsing locale-specific day and month names. The input values take the ISO-639 Language code with an optional ISO-3166 country code appended to it with an underscore.

Optional
lookupFieldstring

The name of the lookup field whose value identifies a record in the lookup data.The uniqueness of the values is ensured by deduplicating records during upload, if necessary.

Required
overwriteboolean

If false and the file already exists, the upload fails. Set to true to allow overwriting existing files.

Optional
parsePatternstring

The DPL pattern to parse the uploaded data. Every pattern match produces a record.

Required
skippedRecordsinteger

The number of initial records to discard. Can be used to skip header rows.

Optional
timezonestring

The timezone for parsing time and date fields. The list of valid input values matches that of the IANA Time Zone Database (TZDB).

Optional

Request body JSON model

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.

{
  "content": "string",
  "request": {
    "autoFlatten": true,
    "description": "Description of my lookup data",
    "displayName": "My lookup data",
    "dt.cost.costcenter": "string",
    "dt.cost.product": "string",
    "filePath": "/lookups/mydata",
    "locale": "en_US",
    "lookupField": "id",
    "overwrite": false,
    "parsePattern": "LD:id ',' LD:value",
    "skippedRecords": 0,
    "timezone": "UTC"
  }
}

Response

Response codes

CodeTypeDescription
200ResourceUploadResponse

The requested table has been saved successfully.

400ErrorEnvelope

Bad request for uploading the lookup data.

401ErrorEnvelope

Unauthorized.

403ErrorEnvelope

Access forbidden.

409ErrorEnvelope

Conflict because the requested table already exists and override parameter was set to false.

413ErrorEnvelope

The uploaded file or the JSON request were too large.

429ErrorEnvelope

Too many concurrent requests.

500ErrorEnvelope

Internal Server Error

4XXErrorEnvelope

Client Error

5XXErrorEnvelope

Server Error

Response body objects

The ResourceUploadResponse object

ElementTypeDescription
discardedDuplicatesinteger

The number of records that were discarded because their lookup field was not unique.

fileSizeinteger

The size of the tabular file in the resource store, in bytes.

patternMatchesinteger

The number of records in the uploaded file that match the parse pattern.

recordsinteger

The number of records in the final lookup data.

skippedRecordsinteger

The number of records that were skipped, based on the skippedRecords parameter in the request.

uploadedBytesinteger

The number of bytes that were sent in the request content.

The ErrorEnvelope object

ElementTypeDescription
errorExceptionalReturn-

The ExceptionalReturn object

ElementTypeDescription
codeinteger-
errorDetails(CustomValidationErrorInfo | InvalidAuditEventsErrorInfo | MediaTypeErrorInfo | ParameterErrorInfo | ProxyErrorInfo | QueryFrontendRawErrorInfo | RequestBodyErrorInfo)[]-
messagestring-

The CustomValidationErrorInfo object

The ErrorInfo object

ElementTypeDescription
messagestring-

The InvalidAuditEventsErrorInfo object

The MediaTypeErrorInfo object

The ParameterErrorInfo object

The ProxyErrorInfo object

The QueryFrontendRawErrorInfo object

The RequestBodyErrorInfo object

Response body JSON models

{
  "fileSize": 1024,
  "uploadedBytes": 2028,
  "patternMatches": 120,
  "skippedRecords": 5,
  "discardedDuplicates": 20,
  "records": 95
}
{
  "error": {
    "code": 400,
    "message": "Upload failed: Parse pattern must not be blank."
  }
}
Related tags
Platform APIDynatrace Platform