> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xdr-5-api/cortex-platform/lookup-datasets.md). # Lookup Datasets APIs for lookup datasets ## Add or update data in a lookup dataset > Add or update data in a lookup dataset. > \\ > > \ > When updating data, any field not specified in the \`data\` field, but specified on at least one of the rows, will be set to \`None\`. > \\ > > \ > The \[Add or update data in a lookup dataset]\() endpoint does not support concurrent edits. Sending concurrent calls to this endpoint can cause data to be unintentionally overwritten or deleted. To allow sufficient time for each API call to complete its operation before initiating another one, assume that 1000 entries can be added per API every 10 seconds. > \\ > > \ > \*\*Note: \*\* > \\ > > \ > \- The maximum size of a lookup dataset is 50 MB. Attempting to exceed this limit will fail. > \ > \- Requests time out after three minutes. > \\ > > \ > \*\*Required license:\*\* Cortex XDR. ```json {"openapi":"3.0.0","info":{"title":"Cortex XDR Platform APIs","version":"Cortex XDR 5.2"},"tags":[{"name":"Lookup Datasets","description":"APIs for lookup datasets"}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/xql/lookups/add_data":{"post":{"tags":["Lookup Datasets"],"summary":"Add or update data in a lookup dataset","description":"Add or update data in a lookup dataset.\r\n\r\nWhen updating data, any field not specified in the `data` field, but specified on at least one of the rows, will be set to `None`.\r\n\r\nThe [Add or update data in a lookup dataset](https://app.gitbook.com/s/FK89utN7l3ilSek2DmU5/cortex-platform/lookup-datasets#post-public_api-v1-xql-lookups-add_data) endpoint does not support concurrent edits. Sending concurrent calls to this endpoint can cause data to be unintentionally overwritten or deleted. To allow sufficient time for each API call to complete its operation before initiating another one, assume that 1000 entries can be added per API every 10 seconds.\r\n\r\n**Note: ** \r\n\r\n- The maximum size of a lookup dataset is 50 MB. Attempting to exceed this limit will fail.\r\n- Requests time out after three minutes.\r\n\r\n**Required license:** Cortex XDR.","operationId":"post-public_api-v1-xql-lookups-add_data","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"dataset_name":{"type":"string","description":"Unique dataset name"},"key_fields":{"type":"array","description":"The fields used to identify existing records. If there is not an exact match to the key_fields specified, a new row is created. \r\nWhen you specify `key_fields`, these fields are mandatory in data entries. When `key_fields` are not specified, existing data entries are not updated, and new entries are added with the specified data.","items":{"type":"string"}},"data":{"type":"object","description":"Key-value pairs of data entries.","additionalProperties":{"type":"string"}}},"required":["dataset_name","data"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"added":{"type":"integer"},"updated":{"type":"integer"},"skipped":{"type":"integer"}}}}}}}}}}} ``` ## Remove data from a lookup dataset > Remove data from a dataset based on the specified parameters. If any one of the filter sets are not found, the API does not delete any data. > \\ > > \ > The \[Remove data from a lookup dataset]\() endpoint does not support concurrent edits. Sending concurrent calls to this endpoint can cause data to be unintentionally overwritten or deleted. To allow sufficient time for each API call to complete its operation before initiating another one, assume that 1000 entries can be added per API every 10 seconds. > \\ > > \ > \*\*Note:\*\* > \ > \- All lookup entries matching any of the filter blocks are deleted. To match a filter block, a lookup entry must match all the specified fields as if there were an \`AND\` operator between them. > \ > \- Requests time out after three minutes. > \\ > > \ > \*\*Required license:\*\* Cortex XDR. ```json {"openapi":"3.0.0","info":{"title":"Cortex XDR Platform APIs","version":"Cortex XDR 5.2"},"tags":[{"name":"Lookup Datasets","description":"APIs for lookup datasets"}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/xql/lookups/remove_data":{"post":{"tags":["Lookup Datasets"],"summary":"Remove data from a lookup dataset","description":"Remove data from a dataset based on the specified parameters. If any one of the filter sets are not found, the API does not delete any data.\r\n\r\nThe [Remove data from a lookup dataset](https://app.gitbook.com/s/FK89utN7l3ilSek2DmU5/cortex-platform/lookup-datasets#post-public_api-v1-xql-lookups-remove_data) endpoint does not support concurrent edits. Sending concurrent calls to this endpoint can cause data to be unintentionally overwritten or deleted. To allow sufficient time for each API call to complete its operation before initiating another one, assume that 1000 entries can be added per API every 10 seconds.\r\n\r\n**Note:** \r\n- All lookup entries matching any of the filter blocks are deleted. To match a filter block, a lookup entry must match all the specified fields as if there were an `AND` operator between them. \r\n- Requests time out after three minutes.\r\n\r\n**Required license:** Cortex XDR.","operationId":"post-public_api-v1-xql-lookups-remove_data","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"dataset_name":{"type":"string","description":"The name of the dataset to delete."},"filters":{"type":"object","description":"Key-value pairs of fields to query in datasets. A lookup entry must match all the specified fields as if there were an `AND` operator between them.\r\nYou can use one or more fields, up to the number of fields in the schema.","additionalProperties":{"type":"string"}}},"required":["dataset_name","filters"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"integer","description":"Number of entries deleted successfully."}}}}}}}}}}} ``` ## Get data from a lookup dataset > Get data from a lookup dataset according to the specified filter fields. All lookup entries matching any of the filter blocks are returned. To match a filter block, a lookup entry must match all the specified fields as if there were an \`AND\` operator between them. If no filters are specified, return all lookup entries. > \\ > > \ > \*\*Note:\*\* > \\ > > \ > \- The maximum number of entries returned is 10,000. > \ > \- Requests time out after three minutes. > \\ > > \ > \*\*Required license:\*\* Cortex XDR. ```json {"openapi":"3.0.0","info":{"title":"Cortex XDR Platform APIs","version":"Cortex XDR 5.2"},"tags":[{"name":"Lookup Datasets","description":"APIs for lookup datasets"}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/xql/lookups/get_data":{"post":{"tags":["Lookup Datasets"],"summary":"Get data from a lookup dataset","description":"Get data from a lookup dataset according to the specified filter fields. All lookup entries matching any of the filter blocks are returned. To match a filter block, a lookup entry must match all the specified fields as if there were an `AND` operator between them. If no filters are specified, return all lookup entries. \r\n\r\n**Note:** \r\n\r\n- The maximum number of entries returned is 10,000. \r\n- Requests time out after three minutes.\r\n\r\n**Required license:** Cortex XDR.","operationId":"post-public_api-v1-xql-lookups-get_data","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"dataset_name":{"type":"string","description":"Name of the dataset to query."},"filters":{"type":"array","description":"Key-value pairs of fields to query in a dataset. A lookup entry must match all the specified fields as if there were an `AND` operator between them.\r\nYou can use one or more fields, up to the number of fields in the schema.","items":{"type":"object","additionalProperties":{"type":"string"}}},"limit":{"type":"integer","description":"The maximum number of results to return. If this is not specified, return all lookup entries that match the filter criteria."}},"required":["dataset_name"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"type":"string"}},"filter_count":{"type":"integer","description":"Number of entries that match the filter."},"total_count":{"type":"integer","description":"Total number of entries."}}}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/xdr-5-api/cortex-platform/lookup-datasets.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.