Reload Lookup Data Task

Reprocesses entity or relation records to update attributes using lookup values when previous lookup strategies were incorrect or outdated.

The reloadLookups task API creates a task which processes the entity or relation records to fix inconsistencies in attributes that use lookup values. Use it when unresolved or outdated lookup values are caused by configuration errors, missing source mappings, or inconsistent use of the resolveLookupCode parameter.

You can run the task on either entities or relations. It targets all objects, objects of specific types, specific URIs, or a combination of these filters. It supports the updatedSince parameter to process records updated after the specified Unix timestamp, and can run in parallel across multiple task parts to improve performance on large datasets.

HTTP method and endpoint

Use the following HTTP method and endpoint path to reload lookup values for entity or relation records.

POST {{ApplicationURL}}/api/{{tenantId}}/reloadLookups

Replace {{ApplicationURL}} with the target URL and {{tenantId}} with the ID of the target tenant.

Request headers

The following request headers must be included.


Header	Value	Required
`Content-Type`	`application/json`	Yes
`Authorization`	`Bearer {{access_token}}`	Yes

Request body

The following table describes the request body parameters, including accepted values and defaults.

Table 1. Parameters
Parameter	Type	Required	Description
`objectType`	String	No	The object type to run the task on. Values: `Entity` (default), `Relation`.
`updatedSince`	Long	No	Filters records updated after the specified Unix timestamp (in milliseconds).
`distributed`	Boolean	No	Runs the task in parallel mode, with each thread processing a different subset of the input data.
`taskPartsCount`	Integer	No	The number of parallel task instances to run (when `distributed=true`).
`retryCount`	Integer	No	The number of retry attempts for each failed batch. Default is `1`.
`uris`	Array of Strings	No	The selected object URIs to run the task on.
`types`	Array of Strings	No	The object types (entity or relation types) to include in the task.

Example request

Use the following example to see how a complete request is structured with headers and a JSON body to run the task on selected entity URIs.

{
    "uris": [
        "entities/0DK9ocI",
        "entities/0DK9ssY",
        "entities/0DK9x8o"
    ]
}

Response fields

The response body includes standard task metadata (such as id, status, and name) along with a parameters object that contains task-specific input values.

The following table describes the fields inside the parameters object.


Field	Type	Description
`tenantId`	String	Tenant identifier where the task was executed.
`updatedSince`	String	Filters objects updated after the given Unix time in milliseconds.
`uriList`	String	List of object URIs included in the task.
`objectType`	String	Object type (`Entity` or `Relation`). Empty string defaults to `Entity`.
`types`	String	List of object types (Example, `["Organization"]`).

Example response

The following example shows the response when the task runs on specific entity URIs..

[
    {
        "id": "3f6b159a-6ff9-4011-bc03-cfa015fcd4d0",
        "groupId": "2d6ca9da-6eb6-46ce-aa2f-202bf18ff44c",
        "createdTime": 1770719454159,
        "createdBy": "pradeep.krishnappa@reltio.com",
        "updatedTime": 1770719454159,
        "updatedBy": "pradeep.krishnappa@reltio.com",
        "type": "com.reltio.businesslogic.tasks.lookups.ReloadLookupsDataTask",
        "status": "SCHEDULED",
        "name": "Reload Lookups Data background task in tenant mgupta. (started by pradeep.krishnappa@reltio.com)",
        "createdOnHost": "dataload-7ddbb56776-jnz2f",
        "parallelExecution": false,
        "nodesGroup": "default",
        "parameters": {
            "tenantId": "mgupta",
            "updatedSince": "0",
            "uriList": "[\"entities/0DK9ocI\",\"entities/0DK9ssY\",\"entities/0DK9x8o\"]",
            "objectType": "",
            "cbErrored": "false",
            "types": "[]"
        },
        "currentState": {},
        "duration": "0s"
    }
]

Additional request examples

The following examples show how to structure requests for common use cases, such as running the task on all entities, filtering by type, targeting specific object URIs, or executing in parallel. The response structure remains the same, with parameters reflecting each specific request.

Run on all entities:

POST {{ApplicationURL}}/api/{{tenantId}}/reloadLookups

{}

Run on relations with ID 0000sdR, 00003gw, 0000G6r:

POST {{ApplicationURL}}/api/{{tenantId}}/reloadLookups?objectType=Relation

{
  "uris": [
    "relations/0000sdR",
    "relations/00003gw",
    "relations/0000G6r"
  ]
}

Run on entities with ID 0000Ifd, 00005Kc, 0000EPN, with Organization type:

POST {{ApplicationURL}}/api/{{tenantId}}/reloadLookups

{
  "uris": [
        "entities/0000Ifd",
        "entities/00005Kc",
        "entities/0000EPN"
    ],
    "types": [
        "Organization"
    ]
}

Run on all entities of type Organization and Location:

POST {{ApplicationURL}}/api/{{tenantId}}/reloadLookups

{
  "types": [
    "Organization",
    "Location"
  ]
}

Run on all entities updated since Jan 1, 2025 at 12:00:00 AM GMT in 2 parallel task instances:

POST {{ApplicationURL}}/api/{{tenantId}}/reloadLookups?updatedSince=1735689600000&distributed=true&taskPartsCount=2

{}

Run on all relations in the tenant:

POST {{ApplicationURL}}/api/{{tenantId}}/reloadLookups?objectType=Relation

{}

Retry Logic

Objects are processed in batches of 150. Each batch is read using RDM transcoding and then written back to the database. If an exception occurs, the entire batch is retried based on the value of the retryCount parameter. The default value for retryCount is 1.

Retrieve task status

Use the following request to check the status of the task while it's in progress or after it completes.

Example request

GET {{ApplicationURL}}/api/{{tenantId}}/tasks/{{TaskId}}

Example response

{
    "id": "3f6b159a-6ff9-4011-bc03-cfa015fcd4d0",
    "groupId": "2d6ca9da-6eb6-46ce-aa2f-202bf18ff44c",
    "createdTime": 1770719454159,
    "createdBy": "pradeep.krishnappa@reltio.com",
    "updatedTime": 1770719454159,
    "updatedBy": "pradeep.krishnappa@reltio.com",
    "type": "com.reltio.businesslogic.tasks.lookups.ReloadLookupsDataTask",
    "status": "COMPLETED",
    "name": "Reload Lookups Data background task in tenant mgupta. (started by pradeep.krishnappa@reltio.com)",
    "createdOnHost": "dataload-7ddbb56776-jnz2f",
    "executedOnHost": "dataprocess-5554d7cdf5-gcrgh",
    "parallelExecution": false,
    "nodesGroup": "default",
    "startTime": 1770719469626,
    "endTime": 1770719490250,
    "parameters": {
        "tenantId": "mgupta",
        "updatedSince": "0",
        "uriList": "[\"entities/0DK9ocI\",\"entities/0DK9ssY\",\"entities/0DK9x8o\"]",
        "objectType": "",
        "logErrors": "https://reltio-api-tasks-internal.s3.amazonaws.com/reloadLookupsDataTask/mgupta/3f6b159a-6ff9-4011-bc03-cfa015fcd4d0/failedObjects.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20260210T103110Z&X-Amz-SignedHeaders=host&X-Amz-Expires=604799&X-Amz-Credential=AKIAIMVSSDXKTO4I7LPQ%2F20260210%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=f5cfdd89be90560a5899c82725e81e7987457d52fda9f960b0605785d5de60dc",
        "cbErrored": "false",
        "types": "[]"
    },
    "currentState": {
        "lastExecutionEC2Instances": "i-00cdb8fbfe32bee3e",
        "numberOfFailedToPublishEvents": 0,
        "lastHourThroughput": 0.0,
        "numberOfProcessedObjects": 3,
        "errors": [],
        "status": "Completed"
    },
    "throughput": 0.15,
    "duration": "20s"
}

Unify and manage your data

Reload Lookup Data Task

HTTP method and endpoint

Request headers

Request body

Example request

Response fields

Example response

Additional request examples

Retry Logic

Retrieve task status

Footer