Analytics

Read aggregated import statistics, health, and the settings behind them.

Retrieving import statistics

get

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

Retrieves aggregated import metrics for a time window: headline counters and rates, a time series bucketed by day, week, or month, per-stream health, the top failing streams, an error breakdown, and how many streams were added or removed.

To narrow the scope, use:

configId for one configuration
configIds for several configurations
streamId for one stream

When none of them are given, the whole tenant is summarised. Use sections to fetch only the parts you need — an unrequested section is returned as null.

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

Query parameters

configIdstring · uuidOptional

Restricts the statistics to a single configuration.

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

configIdsstringOptional

Restricts the statistics to several configurations, as a comma-separated list of identifiers. Ignored when configId is given.

Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7,550e8400-e29b-41d4-a716-446655440000

streamIdstring · uuidOptional

Restricts the statistics to a single stream. Takes precedence over the configuration filters.

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

fromstring · date-timeOptional

The start of the window, as an ISO-8601 instant. When omitted, defaults to 30 days ago.

Example: 2024-05-01T00:00:00Z

tostring · date-timeOptional

The end of the window, as an ISO-8601 instant. Exclusive. When omitted, defaults to now.

Example: 2024-05-31T00:00:00Z

granularitystring · enumOptional

The bucket size of the returned time series.

Default: DAYExample: DAYPossible values:

sectionsstringOptional

A comma-separated list of the sections to compute: TOTALS, STREAMS, ERRORS, CHANGES. When omitted, defaults to all sections. A section not requested through the sections parameter is returned as null.

Example: TOTALS,ERRORS

Responses

200

The request was successful. The statistics are returned.

application/json

Aggregated import metrics for the requested window and scope. A section that was not requested via the sections parameter is returned as null.

400

The window or a filter value is invalid.

application/json

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}/stats

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

{
  "summary": {
    "totalRuns": 42,
    "succeeded": 38,
    "partial": 3,
    "failed": 1,
    "cancelled": 0,
    "recordsRead": 125000,
    "created": 4300,
    "updated": 98000,
    "skipped": 22000,
    "deleted": 700,
    "failedRecords": 130,
    "successRate": 0.905,
    "failureRate": 0.001,
    "deletionRate": 0.006,
    "skipRate": 0.176,
    "avgRunDurationSec": 184.5,
    "avgCreatedPerRun": 102.4,
    "avgUpdatedPerRun": 2333.3,
    "distinctEntities": 87000,
    "activeRuns": 1
  },
  "series": [
    {
      "bucket": "2026-07-19T00:00:00.000Z",
      "runs": 3,
      "succeeded": 3,
      "failed": 0,
      "recordsRead": 4200,
      "created": 120,
      "updated": 3900,
      "deleted": 10,
      "skipped": 170,
      "failedRecords": 0
    }
  ],
  "streamHealth": [
    {
      "streamId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "configId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Products",
      "targetType": "product",
      "lastRunStatus": "SUCCEEDED",
      "lastRunAt": "2026-07-20T02:00:00.000Z",
      "watermarkAgeSeconds": 7200,
      "failureRatio": 0.002,
      "health": "GREEN",
      "thresholds": {
        "failureRatioAmber": 0.01,
        "failureRatioRed": 0.1,
        "staleAmberHours": 48,
        "staleRedHours": 168,
        "failedRunIsRed": true,
        "customised": false
      }
    }
  ],
  "topFailingStreams": [
    {
      "streamId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Products",
      "count": 87
    }
  ],
  "errorBreakdown": [
    {
      "stage": "UPSERT",
      "errorCode": "VALIDATION",
      "count": 54
    }
  ],
  "streamChanges": {
    "added": 2,
    "removed": 1,
    "trackingSince": "2026-06-11T08:00:00.000Z",
    "series": [
      {
        "bucket": "2026-07-19T00:00:00.000Z",
        "added": 1,
        "removed": 0
      }
    ]
  }
}

Retrieving job groups

get

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

Retrieves the tenant's job groups. A job group is a named set of import configurations, used to scope the analytics to the imports that matter to you. Groups are stored per tenant and shared by everyone working on it.

Creating, changing, and deleting groups requires the importtool.import_manage scope.

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

Responses

200

The request was successful. The job groups are returned.

application/json

A named set of import configurations, used to scope the import statistics.

idstring · uuidOptional

The job group identifier.

Example: 9f8c7b6a-5d4e-3f2a-1b0c-9d8e7f6a5b4c

namestringOptional

The job group name. Unique within the tenant.

Example: Nightly master data

configIdsstring · uuid[]Optional

The configurations in the group.

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

createdAtstring · date-timeOptional

When the group was created.

Example: 2024-05-01T09:00:00.000Z

updatedAtstring · date-timeOptional

When the group was last changed.

Example: 2024-05-02T11:30:00.000Z

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}/dashboard/job-groups

GET /importtool/{tenant}/dashboard/job-groups HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "9f8c7b6a-5d4e-3f2a-1b0c-9d8e7f6a5b4c",
    "name": "Nightly master data",
    "configIds": [
      "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    ],
    "createdAt": "2026-07-01T10:15:30.000Z",
    "updatedAt": "2026-07-20T08:00:00.000Z"
  }
]

Retrieving the tenant's health thresholds

get

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

Retrieves the tenant-wide thresholds that decide whether a stream is reported as GREEN, AMBER, or RED in the import statistics, together with the built-in defaults they fall back to.

Thresholds resolve field by field, from the most specific level to the least specific: stream, configuration, tenant, then the built-in default. An unset field falls back to the value at the next less-specific level.

Changing the tenant-wide thresholds requires the importtool.import_manage scope.

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

Responses

200

The request was successful. The thresholds are returned.

application/json

The tenant-wide thresholds, together with the built-in defaults they fall back to.

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}/settings/health-thresholds

GET /importtool/{tenant}/settings/health-thresholds HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "thresholds": {
    "failureRatioAmber": 0.05,
    "staleRedHours": 72
  },
  "builtInDefaults": {
    "failureRatioAmber": 0.01,
    "failureRatioRed": 0.1,
    "staleAmberHours": 48,
    "staleRedHours": 168,
    "failedRunIsRed": true
  }
}

PreviousData

NextLicense

Last updated 7 days ago

Was this helpful?