Runs

Trigger, monitor, and cancel import runs.

Retrieving run history

get

This functionality is in preview mode - some of the features may not be fully operational yet.

Retrieves the run history for a configuration, most recent first.

Required scopes

This endpoint requires the following scopes:

• : Needed to trigger, schedule, monitor, and cancel import runs and to read configurations, streams, schedules, runs, and imported data.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

The tenant you want to access.

Example: mytenant

configIdstring · uuidRequired

The configuration identifier.

Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

Query parameters

pageintegerOptional

The zero-based page number.

Default: 0Example: 0

sizeintegerOptional

The page size.

Example: 20

Responses

200

The request was successful. The run history is returned.

application/json

Pagination metadata for a page of results.

totalElementsintegerOptional

The total number of elements across all pages.

Example: 1250

totalPagesintegerOptional

The total number of pages.

Example: 63

numberintegerOptional

The current zero-based page number.

Example: 0

sizeintegerOptional

The page size.

Example: 20

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

500

Internal Service Error occurred.

application/json

get/importtool/{tenant}/configs/{configId}/runs

GET /importtool/{tenant}/configs/{configId}/runs HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "totalElements": 3,
  "totalPages": 1,
  "number": 0,
  "size": 20,
  "content": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "configId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "tenant": "mytenant",
      "trigger": "MANUAL",
      "origin": "Dashboard",
      "status": "SUCCEEDED",
      "mode": "DELTA",
      "startedAt": "2026-07-27T02:00:00.000Z",
      "finishedAt": "2026-07-27T02:04:12.000Z",
      "recordsRead": 1250,
      "created": 40,
      "updated": 1180,
      "skipped": 25,
      "failed": 5,
      "deleted": 0,
      "message": "Import completed with 5 record failures."
    }
  ]
}

Triggering an import run

post

This functionality is in preview mode - some of the features may not be fully operational yet.

Starts an import run for the configuration and returns immediately with the run in a running state; progress is streamed over Server-Sent Events. At most one run is active per configuration.

Required scopes

This endpoint requires the following scopes:

• : Needed to trigger, schedule, monitor, and cancel import runs and to read configurations, streams, schedules, runs, and imported data.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

The tenant you want to access.

Example: mytenant

configIdstring · uuidRequired

The configuration identifier.

Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

Body

modestring · enumOptional

The run mode. When omitted, defaults to DELTA.

Example: DELTAPossible values:

dryRunbooleanOptional

When true, the run maps and validates but performs no remote writes.

Example: false

forcebooleanOptional

When true, every extracted record is rewritten, even if unchanged. It bypasses the idempotency skip-if-unchanged check. Use it to force target IDs and values to be rewritten.

Example: false

sampleSizeinteger · min: 1 · max: 100Optional

Dry-run only. How many mapped records to sample per stream for the preview returned as dryRunSample. Clamped to 1-100; defaults to 25.

Example: 25

originstring · max: 40Optional

What requested this run. Examples: Dashboard, an integration scenario name, or a scheduler name. The trigger field records only MANUAL or SCHEDULED. Use origin when more than one system calls this endpoint. If you omit origin or send a blank value, the service stores the trigger value. The service rejects values longer than 40 characters and values that contain control characters. It does not shorten them.

Example: Make scenario 42

Responses

200

The request was successful. The run has been started.

application/json

An import run and its reconciled counters.

idstring · uuidOptional

The run identifier.

Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

configIdstring · uuidOptional

The configuration the run belongs to.

Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

tenantstringOptional

The owning tenant.

Example: mytenant

triggerstring · enumOptional

What triggered the run.

Example: MANUALPossible values:

originstringOptional

What requested the run. The origin value from the trigger request, or the trigger value when origin was omitted. Use this field to distinguish a dashboard run from a run started by an integration scenario. The field is absent on runs recorded before it existed.

Example: Dashboard

statusstring · enumOptional

The run status.

Example: SUCCEEDEDPossible values:

modestring · enumOptional

The run mode.

Example: DELTAPossible values:

startedAtstring · date-timeOptional

When the run started.

Example: 2026-07-27T02:00:00.000Z

finishedAtstring · date-timeOptional

When the run finished.

Example: 2026-07-27T02:04:12.000Z

recordsReadintegerOptional

Records read (created + updated + skipped + deleted + failed).

Example: 1250

createdintegerOptional

Records created.

Example: 40

updatedintegerOptional

Records updated.

Example: 1180

skippedintegerOptional

Records skipped because they were unchanged.

Example: 25

failedintegerOptional

Records that failed.

Example: 5

deletedintegerOptional

Records deleted.

Example: 0

duplicateKeysintegerOptional

Source rows that repeat a key already imported in this run. The import keeps the last row of each repeated key and discards earlier rows. Duplicate keys do not fail the run; they mean the source feed is not unique on the key the stream imports by.

Example: 25907

unresolvedParentsintegerOptional

Child records that were not imported because their parent could not be found. Counted separately from skipped, which counts records that were already up to date.

Example: 25370

messagestringOptional

A terminal status message, typically set on failure.

Example: Import completed with 5 record failures.

retryOfRunIdstring · uuidOptional

When the run retries another run's failed records, the identifier of that original run.

Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

forcebooleanOptional

Whether the run rewrote every record, bypassing the skip-if-unchanged check.

Example: false

dryRunbooleanOptional

Whether the run only extracted, mapped, and validated, writing nothing to the target. A dry run legitimately reports zero for every counter, so this distinguishes it from a run that wrote nothing because it failed.

Example: false

cancelRequestedbooleanOptional

Whether cancellation has been requested for a run that is still finishing.

Example: false

dryRunSampleSizeintegerOptional

For a dry run, how many mapped records were kept as a sample.

Example: 10

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

409

The request conflicts with the current state of the resource.

application/json

500

Internal Service Error occurred.

application/json

post/importtool/{tenant}/configs/{configId}/runs

POST /importtool/{tenant}/configs/{configId}/runs HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "mode": "FULL",
  "origin": "Dashboard"
}

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "configId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "tenant": "mytenant",
  "trigger": "MANUAL",
  "origin": "Dashboard",
  "status": "RUNNING",
  "mode": "FULL",
  "startedAt": "2026-07-27T02:00:00.000Z",
  "finishedAt": null,
  "recordsRead": 120,
  "created": 10,
  "updated": 100,
  "skipped": 8,
  "failed": 2,
  "deleted": 0,
  "message": null
}

Retrieving a run

get

This functionality is in preview mode - some of the features may not be fully operational yet.

Retrieves a run's status together with its per-stream progress.

Required scopes

This endpoint requires the following scopes:

• : Needed to trigger, schedule, monitor, and cancel import runs and to read configurations, streams, schedules, runs, and imported data.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

The tenant you want to access.

Example: mytenant

runIdstring · uuidRequired

The run identifier.

Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

Responses

200

The request was successful. The run and its streams are returned.

application/json

A run together with its per-stream progress.

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

404

The requested resource does not exist.

application/json

500

Internal Service Error occurred.

application/json

get/importtool/{tenant}/runs/{runId}

GET /importtool/{tenant}/runs/{runId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "run": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "configId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "tenant": "mytenant",
    "trigger": "MANUAL",
    "origin": "Dashboard",
    "status": "SUCCEEDED",
    "mode": "DELTA",
    "startedAt": "2026-07-27T02:00:00.000Z",
    "finishedAt": "2026-07-27T02:04:12.000Z",
    "recordsRead": 1250,
    "created": 40,
    "updated": 1180,
    "skipped": 25,
    "failed": 5,
    "deleted": 0,
    "message": "Import completed with 5 record failures."
  },
  "streams": [
    {
      "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
      "runId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "streamId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "streamName": "Products",
      "status": "PARTIAL",
      "recordsRead": 1250,
      "created": 40,
      "updated": 1180,
      "skipped": 25,
      "failed": 5,
      "deleted": 0,
      "message": "5 records failed validation."
    }
  ]
}

Streaming run progress

get

This functionality is in preview mode - some of the features may not be fully operational yet.

Streams a run's progress as Server-Sent Events: an initial snapshot (run and streams), then a stream event per processed batch, and a final run event when the run finishes.

Required scopes

This endpoint requires the following scopes:

• : Needed to trigger, schedule, monitor, and cancel import runs and to read configurations, streams, schedules, runs, and imported data.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

The tenant you want to access.

Example: mytenant

runIdstring · uuidRequired

The run identifier.

Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

Responses

200

The event stream was opened.

text/event-stream

stringOptionalExample: event: snapshot data: {"run":{"id":"9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d","status":"RUNNING"},"streams":[{"streamName":"Products","status":"RUNNING","recordsRead":120}]} event: stream data: {"streamName":"Products","status":"RUNNING","recordsRead":240,"created":20,"updated":210,"failed":2} event: run data: {"id":"9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d","status":"SUCCEEDED","recordsRead":1250}

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

500

Internal Service Error occurred.

application/json

get/importtool/{tenant}/runs/{runId}/events

GET /importtool/{tenant}/runs/{runId}/events HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

event: snapshot
data: {"run":{"id":"9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d","status":"RUNNING"},"streams":[{"streamName":"Products","status":"RUNNING","recordsRead":120}]}

event: stream
data: {"streamName":"Products","status":"RUNNING","recordsRead":240,"created":20,"updated":210,"failed":2}

event: run
data: {"id":"9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d","status":"SUCCEEDED","recordsRead":1250}

Cancelling a run

post

This functionality is in preview mode - some of the features may not be fully operational yet.

Requests cancellation of an active run. By default the cancellation is cooperative; with force=true the run is stopped immediately and its configuration is unblocked.

Required scopes

This endpoint requires the following scopes:

• : Needed to trigger, schedule, monitor, and cancel import runs and to read configurations, streams, schedules, runs, and imported data.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

The tenant you want to access.

Example: mytenant

runIdstring · uuidRequired

The run identifier.

Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

Query parameters

forcebooleanOptional

When true, hard-stops the run immediately.

Default: falseExample: false

Responses

202

The cancellation was accepted.

application/json

The outcome of a cancellation request.

runIdstring · uuidOptional

The run the cancellation targeted.

Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

forcebooleanOptional

Whether a hard stop was requested.

Example: false

acceptedbooleanOptional

Whether the cancellation was accepted. false when the run is unknown or already finished.

Example: true

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

409

The request conflicts with the current state of the resource.

application/json

500

Internal Service Error occurred.

application/json

post/importtool/{tenant}/runs/{runId}/cancel

POST /importtool/{tenant}/runs/{runId}/cancel HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "runId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "force": false,
  "accepted": true
}

Retrieving run errors

get

This functionality is in preview mode - some of the features may not be fully operational yet.

Retrieves the errors recorded during a run, paginated.

Required scopes

This endpoint requires the following scopes:

• : Needed to trigger, schedule, monitor, and cancel import runs and to read configurations, streams, schedules, runs, and imported data.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

The tenant you want to access.

Example: mytenant

runIdstring · uuidRequired

The run identifier.

Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

Query parameters

pageintegerOptional

The zero-based page number.

Default: 0Example: 0

sizeintegerOptional

The page size.

Example: 20

Responses

200

The request was successful. The errors are returned.

application/json

Pagination metadata for a page of results.

totalElementsintegerOptional

The total number of elements across all pages.

Example: 1250

totalPagesintegerOptional

The total number of pages.

Example: 63

numberintegerOptional

The current zero-based page number.

Example: 0

sizeintegerOptional

The page size.

Example: 20

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

500

Internal Service Error occurred.

application/json

get/importtool/{tenant}/runs/{runId}/errors

GET /importtool/{tenant}/runs/{runId}/errors HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "totalElements": 5,
  "totalPages": 1,
  "number": 0,
  "size": 50,
  "content": [
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "runId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "streamId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "naturalKey": "SKU-1001",
      "targetEntity": "emporix.customEntity",
      "stage": "MAPPING",
      "errorCode": "REQUIRED_FIELD_MISSING",
      "message": "Required field 'name' is missing for natural key SKU-1001.",
      "createdAt": "2026-07-27T02:03:41.000Z"
    }
  ]
}

Retrying the failed records of a run

post

This functionality is in preview mode - some of the features may not be fully operational yet.

Starts a new run that reprocesses only the records that failed in the given run, instead of the whole source. The new run is returned immediately and reports its own progress; the original run is left untouched and keeps its counters.

As with any run, at most one run can be active per configuration.

Required scopes

This endpoint requires the following scopes:

• : Needed to trigger, schedule, monitor, and cancel import runs and to read configurations, streams, schedules, runs, and imported data.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

The tenant you want to access.

Example: mytenant

runIdstring · uuidRequired

The run identifier.

Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

Responses

200

The retry run was started.

application/json

An import run and its reconciled counters.

idstring · uuidOptional

The run identifier.

Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

configIdstring · uuidOptional

The configuration the run belongs to.

Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

tenantstringOptional

The owning tenant.

Example: mytenant

triggerstring · enumOptional

What triggered the run.

Example: MANUALPossible values:

originstringOptional

What requested the run. The origin value from the trigger request, or the trigger value when origin was omitted. Use this field to distinguish a dashboard run from a run started by an integration scenario. The field is absent on runs recorded before it existed.

Example: Dashboard

statusstring · enumOptional

The run status.

Example: SUCCEEDEDPossible values:

modestring · enumOptional

The run mode.

Example: DELTAPossible values:

startedAtstring · date-timeOptional

When the run started.

Example: 2026-07-27T02:00:00.000Z

finishedAtstring · date-timeOptional

When the run finished.

Example: 2026-07-27T02:04:12.000Z

recordsReadintegerOptional

Records read (created + updated + skipped + deleted + failed).

Example: 1250

createdintegerOptional

Records created.

Example: 40

updatedintegerOptional

Records updated.

Example: 1180

skippedintegerOptional

Records skipped because they were unchanged.

Example: 25

failedintegerOptional

Records that failed.

Example: 5

deletedintegerOptional

Records deleted.

Example: 0

duplicateKeysintegerOptional

Source rows that repeat a key already imported in this run. The import keeps the last row of each repeated key and discards earlier rows. Duplicate keys do not fail the run; they mean the source feed is not unique on the key the stream imports by.

Example: 25907

unresolvedParentsintegerOptional

Child records that were not imported because their parent could not be found. Counted separately from skipped, which counts records that were already up to date.

Example: 25370

messagestringOptional

A terminal status message, typically set on failure.

Example: Import completed with 5 record failures.

retryOfRunIdstring · uuidOptional

When the run retries another run's failed records, the identifier of that original run.

Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

forcebooleanOptional

Whether the run rewrote every record, bypassing the skip-if-unchanged check.

Example: false

dryRunbooleanOptional

Whether the run only extracted, mapped, and validated, writing nothing to the target. A dry run legitimately reports zero for every counter, so this distinguishes it from a run that wrote nothing because it failed.

Example: false

cancelRequestedbooleanOptional

Whether cancellation has been requested for a run that is still finishing.

Example: false

dryRunSampleSizeintegerOptional

For a dry run, how many mapped records were kept as a sample.

Example: 10

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

404

The requested resource does not exist.

application/json

409

The request conflicts with the current state of the resource.

application/json

500

Internal Service Error occurred.

application/json

post/importtool/{tenant}/runs/{runId}/retry

POST /importtool/{tenant}/runs/{runId}/retry HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "configId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "tenant": "mytenant",
  "trigger": "MANUAL",
  "origin": "Dashboard",
  "status": "RUNNING",
  "mode": "FULL",
  "startedAt": "2026-07-27T02:00:00.000Z",
  "finishedAt": null,
  "recordsRead": 120,
  "created": 10,
  "updated": 100,
  "skipped": 8,
  "failed": 2,
  "deleted": 0,
  "message": null
}