Ctrlk
CommunitySupport PortalYouTubeFree trialSign Up!
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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

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

Was this helpful?