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",
      "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. 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

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:

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

messagestringOptional

A terminal status message, typically set on failure.

Example: Import completed with 5 record failures.

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: 15

{
  "mode": "FULL"
}

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "configId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "tenant": "mytenant",
  "trigger": "MANUAL",
  "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",
    "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"
    }
  ]
}

PreviousSchedules NextData

Last updated 3 days ago

Was this helpful?