> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-references/readme/api-reference-19/models.md).

# Models

## The errorMessage object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"The HTTP status reason phrase, for example `Conflict`.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"description":"Identifier of the resource the error concerns, for example the configuration of a run that conflicts with an active run, or the run a retry was requested for. `null` when the error concerns no single resource.","type":"string","nullable":true},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"One problem causing the error.","type":"object","properties":{"message":{"type":"string","description":"What is wrong."},"field":{"type":"string","description":"The field the problem concerns, when there is one."}}}}},"required":["status","code","message"]}}}}
```

## The ImportConfig object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportConfig":{"title":"Import configuration","type":"object","description":"An import configuration grouping one or more streams.","properties":{"id":{"type":"string","format":"uuid","description":"The configuration identifier."},"tenant":{"type":"string","description":"The owning tenant."},"name":{"type":"string","description":"The configuration name."},"description":{"type":"string","description":"A free-text description."},"sourceConnId":{"type":"string","format":"uuid","description":"The default source connection for the configuration's streams."},"aiEnabled":{"type":"boolean","description":"Whether AI-assisted mapping suggestions are enabled for the configuration."},"enabled":{"type":"boolean","description":"Whether the configuration is active."},"version":{"type":"integer","description":"Incremented on every change to the configuration."},"healthThresholds":{"$ref":"#/components/schemas/HealthThresholds"},"createdBy":{"type":"string","description":"The identifier of the user who created the configuration."},"createdAt":{"type":"string","format":"date-time","description":"When the configuration was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the configuration was last updated."}}},"HealthThresholds":{"title":"Health thresholds","type":"object","description":"The limits that decide whether a stream is reported as `GREEN`, `AMBER`, or `RED`. Each field is optional and resolves independently. An unset field falls back through the hierarchy, from the most specific level to the least specific: stream, configuration, tenant, then the built-in default.","properties":{"failureRatioAmber":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `AMBER`."},"failureRatioRed":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `RED`."},"staleAmberHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `AMBER` when the data's age reaches or exceeds this threshold."},"staleRedHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `RED` when the data's age reaches or exceeds this threshold."},"failedRunIsRed":{"type":"boolean","description":"Whether a failed most-recent run makes the stream `RED` regardless of the other limits."}}}}}}
```

## The ImportFile object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportFile":{"title":"Import file","type":"object","description":"One file a file-based stream has been given, and what became of it.","properties":{"id":{"type":"string","format":"uuid","description":"The file's identifier."},"fileName":{"type":"string","description":"The name the file was given, used to display it and to infer compression."},"size":{"type":"integer","format":"int64","description":"The file's size in bytes."},"status":{"type":"string","enum":["PENDING","IN_PROGRESS","PROCESSED","FAILED"],"description":"Where the file is in its life. Possible values:\n\n* `PENDING` – waiting to be imported.\n* `IN_PROGRESS` – a run has claimed it and is reading it.\n* `PROCESSED` – read to completion. Set only once its records have been written, so a run that\n  fails part-way leaves the file importable.\n* `FAILED` – the stream that read the file finished `FAILED`. The file could not be read\n  (malformed, truncated, wrong charset), or the import failed for another reason, such as the\n  target being unavailable. Such a file can be queued again with the content the service holds, or\n  uploaded again. Records that fail individually do not\n  put a file here: a stream that finishes with record failures still marks its file imported."},"loadRank":{"type":"integer","format":"int64","description":"The position in the drain order. For an incremental feed the order is part of the data: a later file's values win on a key an earlier one also carries."},"queuedAt":{"type":"string","format":"date-time","description":"When the file was added to the queue."},"processedAt":{"type":"string","format":"date-time","description":"When the file finished being imported."},"runId":{"type":"string","format":"uuid","description":"The run that consumed it."},"recordsRead":{"type":"integer","description":"How many records came out of it."},"message":{"type":"string","description":"Why the file ended as it did, when that needs saying — a file superseded by a newer snapshot in the same run, or one imported with record-level failures."}}}}}}
```

## The FileQueue object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"FileQueue":{"title":"File queue","type":"object","description":"What a stream still has to import, and what it has already dealt with.","properties":{"pending":{"type":"array","items":{"$ref":"#/components/schemas/ImportFile"},"description":"The files waiting to be imported, in the order they will be read."},"history":{"type":"array","items":{"$ref":"#/components/schemas/ImportFile"},"description":"Files already dealt with, newest first."},"pendingTruncated":{"type":"boolean","description":"True when more files are waiting than this response carries. The load order cannot be changed while it is true, because an order that cannot name every waiting file has no meaning."},"pendingTotal":{"type":"integer","format":"int64","description":"How many files are waiting in total, however many this response lists."},"lastProcessed":{"description":"The newest file the stream has imported. Absent when it has imported none. Returned whatever `historyLimit` is, because a run with no file waiting reads this file again (a snapshot stream).","type":"object","allOf":[{"$ref":"#/components/schemas/ImportFile"}]}}},"ImportFile":{"title":"Import file","type":"object","description":"One file a file-based stream has been given, and what became of it.","properties":{"id":{"type":"string","format":"uuid","description":"The file's identifier."},"fileName":{"type":"string","description":"The name the file was given, used to display it and to infer compression."},"size":{"type":"integer","format":"int64","description":"The file's size in bytes."},"status":{"type":"string","enum":["PENDING","IN_PROGRESS","PROCESSED","FAILED"],"description":"Where the file is in its life. Possible values:\n\n* `PENDING` – waiting to be imported.\n* `IN_PROGRESS` – a run has claimed it and is reading it.\n* `PROCESSED` – read to completion. Set only once its records have been written, so a run that\n  fails part-way leaves the file importable.\n* `FAILED` – the stream that read the file finished `FAILED`. The file could not be read\n  (malformed, truncated, wrong charset), or the import failed for another reason, such as the\n  target being unavailable. Such a file can be queued again with the content the service holds, or\n  uploaded again. Records that fail individually do not\n  put a file here: a stream that finishes with record failures still marks its file imported."},"loadRank":{"type":"integer","format":"int64","description":"The position in the drain order. For an incremental feed the order is part of the data: a later file's values win on a key an earlier one also carries."},"queuedAt":{"type":"string","format":"date-time","description":"When the file was added to the queue."},"processedAt":{"type":"string","format":"date-time","description":"When the file finished being imported."},"runId":{"type":"string","format":"uuid","description":"The run that consumed it."},"recordsRead":{"type":"integer","description":"How many records came out of it."},"message":{"type":"string","description":"Why the file ended as it did, when that needs saying — a file superseded by a newer snapshot in the same run, or one imported with record-level failures."}}}}}}
```

## The ImportStream object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStream":{"title":"Stream","type":"object","description":"A stream that extracts from a source, maps fields, and upserts into an Emporix target type.","properties":{"id":{"type":"string","format":"uuid","description":"The stream identifier."},"configId":{"type":"string","format":"uuid","description":"The parent configuration."},"name":{"type":"string","description":"The stream name."},"sourceEntity":{"type":"string","description":"The logical source entity or record."},"targetWriter":{"type":"string","description":"Where the stream writes. Possible values:\n\n* `emporix.customEntity` – instances of a custom entity type, named by `targetType`.\n* `emporix.product` – products, including parents and variants. `STANDALONE` streams only.\n* `emporix.category` – categories of the tenant's category tree. `STANDALONE` streams only.\n* `emporix.price` – prices of products.\n* `emporix.availability` – stock of products at a site.\n* `emporix.media` – images of products, linked by URL. The images stay where they are hosted.\n* `emporix.categoryAssignment` – assignments of products to existing categories.\n\nThe price, availability, media, and category assignment writers are normally used by a `FAN_OUT`\nstream whose parent is a product stream. The `FAN_OUT` stream supplies each product's identifier as\n`productId`. A `STANDALONE` stream that uses them maps `productId` itself.\n\nThe writers other than `emporix.customEntity` are catalog writers. The Management Dashboard offers them\nonly to tenants for which Emporix has enabled catalog targets. To have them enabled, contact Emporix\nsupport."},"targetType":{"type":"string","description":"For `emporix.customEntity`, the custom entity type the stream writes to. For the other writers, a label that groups the stream's imported records, for example in imported data and statistics. Defaults to `PRODUCT` for `emporix.product` and `CATEGORY` for `emporix.category`. For a `FAN_OUT` stream into a catalog writer, the service sets the label."},"seq":{"type":"integer","description":"The stream's position in the configuration. Streams are listed in this order. When dependencies do not decide the run order, streams run in this order."},"mode":{"type":"string","enum":["STANDALONE","COMPOSITE_CHILD","COMPOSITE_MERGE","FAN_OUT"],"description":"How the stream contributes to the target. Possible values:\n\n* `STANDALONE` – reads its source and writes its own target objects.\n* `COMPOSITE_CHILD` – reads its source and writes into the objects of the stream named in\n  `compositeParent`.\n* `COMPOSITE_MERGE` – reads its source and adds fields to the objects of the stream named in\n  `compositeParent`.\n* `FAN_OUT` – has no source of its own. It reads the records the stream named in `compositeParent`\n  wrote in the same run, and writes further objects for each of them, for example a product's prices.\n  It runs after that stream. Objects it created earlier for a record that no longer lists them are\n  removed."},"fanOutPath":{"type":"string","description":"`FAN_OUT` only. The array in the parent record whose elements each produce one target object, for example `prices[]`. When omitted, one target object is written per parent record."},"fanOutKey":{"type":"string","description":"`FAN_OUT` only. The element field that identifies an element of `fanOutPath`, for example `currency`, so that a target object keeps its identity when the elements change order. When omitted, a scalar element identifies itself and an object element is identified by its position."},"fanOut":{"type":"boolean","readOnly":true,"description":"Whether the stream is a `FAN_OUT` stream with a parent. Derived from `mode` and `compositeParent`."},"targetOptions":{"type":"object","additionalProperties":true,"description":"Settings for the target writer. Absent when the writer needs none. `emporix.product` reads the\nfollowing settings:\n\n* `matchField` – how existing products are found: `CODE` (the default) or `ID`.\n* `createMissing` – whether products that are not found are created. Defaults to `true`.\n* `variantRole` – what the stream's records are: `NONE` (the default) for products without\n  variants, `PARENT` for parent products, or `VARIANT` for variants of a parent.\n* `variantModel` – how a `PARENT` or `VARIANT` stream's products are linked: `DYNAMIC` (the default)\n  or `TEMPLATE`. With `DYNAMIC`, parents and variants are written as products of type\n  `DYNAMIC_VARIANT` and need no product template. With `TEMPLATE`, parents are written as\n  `PARENT_VARIANT` products and variants as `VARIANT` products of the template in `templateId`.\n* `templateId` – the product template assigned to the products. Required for a `PARENT` or `VARIANT`\n  stream whose `variantModel` is `TEMPLATE`, and not allowed for one whose `variantModel` is `DYNAMIC`.\n* `schemas` – a list of the identifiers of the product mixin schemas the stream writes.\n* `language` – the language of localized fields. Defaults to `en`.\n* `categoryMatchField` – how the categories to assign are found: `CODE` (the default) or `ID`.\n\nA `VARIANT` stream maps each record's parent to `parentCode` or `parentId`, and the record's variant\nattribute values to `variantAttributes.<attribute>`. The parent is found in the Product Service by its\ncode or identifier, so it can come from another stream, another configuration, or the Management\nDashboard. When a stream of the same configuration imports the parents, list it in `dependsOn` so that\nthe parents are written first. With `DYNAMIC`, a `VARIANT` stream can also take its parents from another\n`VARIANT` stream, which adds a level to the product hierarchy, up to four levels. `FAN_OUT` streams of\nthe `VARIANT` stream write the variants' prices, stock, and images.\n\n`emporix.category` reads `language`, and `emporix.categoryAssignment` reads `categoryMatchField`.\n`emporix.price` reads `currency`, `countryCode`, `siteCode`, and `priceModelId`, and\n`emporix.availability` reads `site`. These price and availability settings are fallback values with no\ndefault of their own: a record that does not map the field gets the stream's value. A price needs a\ncurrency and a country, and stock needs a site, from a mapping or from these settings."},"deltaField":{"type":"string","description":"The source field whose value is tracked as the delta watermark. A delta run extracts only the records whose value is newer than the last run's."},"deltaFieldFormat":{"type":"string","enum":["DATE","UNIX_SECONDS","UNIX_MILLIS"],"description":"How the delta field's values are formatted, so they can be compared correctly."},"compositeParent":{"type":"string","description":"For a `COMPOSITE_CHILD`, `COMPOSITE_MERGE`, or `FAN_OUT` stream, the name of the stream it contributes to or fans out from."},"linkingField":{"type":"string","description":"For a composite child stream, the source field holding its parent's key."},"embedAttribute":{"type":"string","description":"For a composite child stream, the parent attribute its records are embedded into."},"childStrategy":{"type":"string","enum":["EMBED","PATCH"],"description":"How a composite child's records reach the parent object."},"writeStrategy":{"type":"string","enum":["PATCH","MERGE_PUT","REPLACE_PUT"],"description":"How an existing target object is updated. Possible values:\n\n* `PATCH` – changes only the mapped fields and keeps everything else.\n* `MERGE_PUT` – reads the object, merges the mapped fields into it, and writes it back whole.\n* `REPLACE_PUT` – replaces the whole object, so fields this import does not manage are cleared.\n\nThe values a stream can use depend on its target writer. The following values are available per\nwriter, with the default listed first:\n\n* `emporix.customEntity` – `PATCH`, `MERGE_PUT`, `REPLACE_PUT`.\n* `emporix.product` and `emporix.category` – `PATCH`.\n* `emporix.media` – `PATCH`, `REPLACE_PUT`.\n* `emporix.price`, `emporix.availability`, and `emporix.categoryAssignment` – `REPLACE_PUT`."},"discriminatorField":{"type":"string","description":"A source field whose value routes each record to a different target type, as defined by `discriminatorMap`."},"discriminatorMap":{"type":"object","additionalProperties":{"type":"string"},"description":"Maps a discriminator value to the target type that receives those records."},"deleteConfig":{"type":"object","description":"How deletes are detected in the source and propagated to the target. Omit for an upsert-only\nstream. `MARKER`: a field on the record flags it as deleted. `TOMBSTONE`: a separate source\nrecord lists the deleted IDs.","properties":{"mode":{"type":"string","enum":["MARKER","TOMBSTONE"],"description":"How a deleted record is recognised."},"markerField":{"type":"string","description":"`MARKER` only. The source field that flags a record as deleted."},"markerValues":{"type":"array","items":{"type":"string"},"description":"`MARKER` only. The values of `markerField` that mean deleted."},"record":{"type":"string","description":"`TOMBSTONE` only. The explicit name of the source record that lists deleted IDs. Omit this\nproperty when the name can be derived from the imported record by adding a prefix or suffix —\nfor example, `invoice_deleted` for an `invoice` stream. Specify it when the deletion record\ndoes not follow that naming convention."}}},"healthThresholds":{"$ref":"#/components/schemas/HealthThresholds"},"createdAt":{"type":"string","format":"date-time","description":"When the stream was created."},"enabled":{"type":"boolean","description":"Whether the stream is active."},"connectionId":{"type":"string","format":"uuid","description":"The source connection this stream reads from, when it has its own. Omitted means the configuration's default connection is used. One configuration can therefore mix sources."},"sourceDataset":{"type":"object","additionalProperties":true,"description":"How this stream addresses its source. The recognised properties depend on the source type; the\nones below are common.\n\n* `keyField` – the source column holding the natural key.\n* `keyFields` and `keyName` – a key that may resolve from more than one column: the first\n  non-empty of `keyFields` wins, and `keyName` is the single canonical name recorded for it,\n  so the same entity keeps one target id whichever column supplied the value. Put the stable\n  identifier first: a lower-priority column winning on an earlier run and a higher-priority\n  one later re-keys the record.\n* `limit` – the maximum number of records one run reads (`Max records`). A positive number\n  only; text or zero means no cap. A dry run reads at most the smaller of this and its own sample size.\n* `record` – the source record, table, or endpoint to read.\n* For a file source: the delimited-file format (`delimiter`, `quote`, `escape`, `charset`,\n  `header`, `skipLines`, `nullLiterals`, `trimValues`, `compression`, `failOnRaggedRow`) and\n  `arrays`, which reshapes repeated flat columns into nested form. The original columns are kept,\n  and each array is added beside them under its name followed by `[]` — for example `lineItems[]`\n  for `lineItems.0.sku`, or `COUNTRIES[]` for a delimited `COUNTRIES` column:\n  * `style` – how a repeated column is recognised: `DOT` (`lineItems.0.sku`), `BRACKET`\n    (`lineItems[0].sku`), `SUFFIX` (`phone_1`), or `NONE` (the default), which recognises no\n    repeated columns.\n  * `delimited` – a list of column names whose cells each hold a list of values.\n  * `separator` – the character a `delimited` cell is split on. Defaults to `;`.\n  * `maxElements` – the maximum number of elements one array can hold. Defaults to 1000; the\n    highest allowed value is 10000. A row with a longer array is not truncated: only that row\n    fails, with the error code `REJECTED_BY_SOURCE`, and the rest of the file is imported.\n* For an HTTP source: `pagination`, `queryParams`, `bodyTemplate`, and `format` (`JSON` or\n  `XML`)."},"fileMode":{"type":"string","enum":["SNAPSHOT","INCREMENTAL"],"description":"For a file-based source, what one file represents. `SNAPSHOT`: each file is the whole picture, so only the most recently arrived one is read, and the per-record content hash decides what is written. A record missing from a newer file is not deleted. `INCREMENTAL`: each file is a change set, so every queued file is read in order and a later file's values win. Defaults to `SNAPSHOT`."},"snapshotFiles":{"type":"boolean","readOnly":true,"description":"Whether the stream treats each file as a snapshot. `true` unless `fileMode` is `INCREMENTAL`."},"parentKeyField":{"type":"string","description":"For an `EMBED` composite child, the source column its parent matches records by. Required for such a stream: without it the parent cannot find its children and writes an empty array."},"hashIncludesDeltaField":{"type":"boolean","description":"Whether the delta field counts as content when deciding a record has changed. Off by default: a modified timestamp is metadata about a change, not content, and a source that restamps every row on reload would otherwise make every run rewrite the whole table. Turn it on only when the timestamp moving genuinely means the record is different."},"schemaAttributes":{"type":"object","additionalProperties":true,"description":"Extra target attributes to declare on the type beyond those the mappings cover, for fields written by something other than this import, keyed by attribute name."},"mappingSchemaVersions":{"type":"object","additionalProperties":{"type":"integer"},"description":"The target mixin schema version this stream's mappings were written against, keyed by schema id. An instance is validated against the version it was written under, so a stream pinned here is also written at that version. Set by the mapping editor, not by a stream update: a stream update that carried this property would blank the pins."},"abortOnSchemaVersionDrift":{"type":"boolean","description":"Whether to refuse to start a run when a pinned mixin's current version has moved past the pinned one, before any record is read. Opt-in, and bypassed by triggering a run with `force`."},"dependsOn":{"type":"array","items":{"type":"string"},"description":"Names of streams that must run before this one, beyond the ordering a composite parent already implies. A product stream whose `variantRole` is `VARIANT` lists here the stream of the same configuration that imports its parent products, if there is one, so that the parents are written first."},"nameField":{"type":"string","deprecated":true,"description":"The source field used as the instance's display name. Superseded by mapping a field to the standard `name` attribute, which a mapping's transformations also apply to; a `name` mapping wins over this property. Kept for streams configured before that existed."}}},"HealthThresholds":{"title":"Health thresholds","type":"object","description":"The limits that decide whether a stream is reported as `GREEN`, `AMBER`, or `RED`. Each field is optional and resolves independently. An unset field falls back through the hierarchy, from the most specific level to the least specific: stream, configuration, tenant, then the built-in default.","properties":{"failureRatioAmber":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `AMBER`."},"failureRatioRed":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `RED`."},"staleAmberHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `AMBER` when the data's age reaches or exceeds this threshold."},"staleRedHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `RED` when the data's age reaches or exceeds this threshold."},"failedRunIsRed":{"type":"boolean","description":"Whether a failed most-recent run makes the stream `RED` regardless of the other limits."}}}}}}
```

## The Schedule object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"Schedule":{"title":"Schedule","type":"object","description":"A cron schedule for a configuration.","properties":{"id":{"type":"string","format":"uuid","description":"The schedule identifier."},"configId":{"type":"string","format":"uuid","description":"The scheduled configuration."},"cron":{"type":"string","description":"A Spring cron expression with six fields."},"timezone":{"type":"string","description":"The IANA time zone the cron is evaluated in. Defaults to `UTC`."},"enabled":{"type":"boolean","description":"Whether the schedule is active. Defaults to `true`."},"nextFireAt":{"type":"string","format":"date-time","description":"The next fire time."}},"required":["cron"]}}}}
```

## The ImportRun object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportRun":{"title":"Run","type":"object","description":"An import run and its reconciled counters.","properties":{"id":{"type":"string","format":"uuid","description":"The run identifier."},"configId":{"type":"string","format":"uuid","description":"The configuration the run belongs to."},"tenant":{"type":"string","description":"The owning tenant."},"trigger":{"type":"string","enum":["MANUAL","SCHEDULED","RETRY"],"description":"What triggered the run. Possible values:\n\n* `MANUAL` – triggered with the run operation.\n* `SCHEDULED` – started by the configuration's schedule.\n* `RETRY` – created by retrying the failed records of an earlier run. `retryOfRunId` names that run."},"dryRunSample":{"type":"array","description":"Dry-run only. A sample of the mapped records that would be written, so the mapping can be previewed without a real import. Absent on normal runs. Each stream is sampled separately, up to the `sampleSize` set in the run request. A parent stream's records include the records of its composite child streams that have `childStrategy` set to `EMBED` or `PATCH`. Those child records appear in the parent attribute named by the child stream's `embedAttribute`, as a real import writes them. Only child records inside the child stream's own sample are included, so a sampled parent record can show fewer child records than the source contains for that parent, or none. Child records are also sampled under their own stream.","items":{"type":"object","properties":{"stream":{"type":"string","description":"The stream that produced the sample record."},"targetType":{"type":"string","description":"The resolved target type the record would be written to."},"key":{"type":"string","description":"The record's natural/deterministic key."},"fields":{"type":"object","additionalProperties":true,"description":"The mapped target fields that would be written."}}}},"origin":{"type":"string","description":"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."},"status":{"type":"string","enum":["QUEUED","RUNNING","RESUMABLE","SUCCEEDED","PARTIAL","FAILED","CANCELLED","ABORTED"],"description":"The run status. Possible values:\n\n* `QUEUED` – the run waits to start. Nothing has been read yet, and the run has no per-stream\n  progress. `queueWaitingFor` says what the run waits for.\n* `RUNNING` – the run is executing.\n* `RESUMABLE` – the run was interrupted, for example by a service restart, and resumes automatically\n  from its last checkpoint. It is not a final status.\n* `SUCCEEDED` – the run finished, and every record was processed.\n* `PARTIAL` – the run finished, but not completely: some records failed, a limit skipped records,\n  or a stream was not run. The `message` field and the per-stream progress give the details.\n* `FAILED` – the run stopped because of an error.\n* `CANCELLED` – the run was cancelled.\n* `ABORTED` – the service refused to start the run because of the import configuration, for example\n  mappings that have never been published or a changed target schema. Nothing was read or written."},"mode":{"type":"string","enum":["FULL","DELTA"],"description":"The run mode."},"startedAt":{"type":"string","format":"date-time","description":"When the run was requested. If the run was queued first, it began executing later, at `executionStartedAt`."},"executionStartedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the run began executing. Equal to `startedAt`, or later by the time the run spent in the queue. `null` while the run is `QUEUED`, and on runs recorded before the field existed."},"finishedAt":{"type":"string","format":"date-time","description":"When the run finished."},"queuePosition":{"type":"integer","minimum":1,"description":"`QUEUED` runs only. The run's position among the queued runs that can start, where `1` starts next. Runs of all tenants share the queue, and a tenant with fewer runs executing goes first. The value is approximate, because the queue changes while you read it. The field is absent when the run is not queued, when it waits for something other than a worker, or when the service has not yet calculated it."},"queueWaitingFor":{"type":"string","enum":["WORKER","PREVIOUS_RUN","TENANT_LIMIT"],"description":"`QUEUED` runs only. What the run waits for. Possible values:\n\n* `WORKER` – the run waits for a free worker. `queuePosition` gives its place in the queue.\n* `PREVIOUS_RUN` – the run waits for the configuration's current run to finish.\n* `TENANT_LIMIT` – the run waits for one of the tenant's runs to finish, because\n  `maxConcurrentImports` runs are already executing.\n\nThe field is absent when the run is not queued, or when the service has not yet calculated it."},"supersededRequests":{"type":"integer","description":"The number of later scheduled run requests that were added to this run while it was queued. A configuration has at most one queued run, so a scheduled request that arrives while a real run of the whole configuration is queued does not queue a second run."},"lastRequestedAt":{"type":"string","format":"date-time","description":"When the latest scheduled run request counted in `supersededRequests` was made. Absent when `supersededRequests` is `0`."},"recordsRead":{"type":"integer","description":"Records read. The counters reconcile: `recordsRead` = created + updated + skipped + unresolvedParents + deleted + failed + collapsed + embedded. A client that sums only some of them will not balance."},"created":{"type":"integer","description":"Records created."},"updated":{"type":"integer","description":"Records updated."},"skipped":{"type":"integer","description":"Records skipped because they were unchanged."},"failed":{"type":"integer","description":"Records that failed."},"deleted":{"type":"integer","description":"Records deleted."},"duplicateKeys":{"type":"integer","description":"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."},"unresolvedParents":{"type":"integer","description":"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."},"collapsed":{"type":"integer","description":"Source rows that repeated a key already present in the same batch. They are merged before the write, last row wins, and counted here — so the report adds up however the source feed is batched. A repeat in a *later* batch is written again and counted as created or updated instead; `duplicateKeys` is the signal for a feed that is not unique on its key."},"embedded":{"type":"integer","description":"Child records an `EMBED` composite child handed to its parent, which the parent then wrote inside its own instance. One write of the parent covers them all, so they are never counted as created or updated (that would count each line as an instance) and never as skipped (which means \"already up to date\"). If the parent turned out to be unchanged, failed, or absent, these are settled onto `skipped`, `failed`, or `unresolvedParents` once the parent's pass completes."},"message":{"type":"string","description":"A terminal status message, typically set on failure."},"streamIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The streams the run was asked to execute, as sent in `streamIds` when it was triggered. Absent when the run executes every stream of the configuration."},"retryOfRunId":{"type":"string","format":"uuid","description":"When the run retries another run's failed records, the identifier of that original run."},"force":{"type":"boolean","description":"Whether the run rewrote every record, bypassing the skip-if-unchanged check."},"dryRun":{"type":"boolean","description":"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."},"cancelRequested":{"type":"boolean","description":"Whether cancellation has been requested for a run that is still finishing."},"dryRunSampleSize":{"type":"integer","description":"For a dry run, how many mapped records were kept as a sample."},"dryRunPublished":{"type":"boolean","description":"Dry-run only. Whether the dry run used the published mappings (`true`) or the draft mappings (`false`)."},"mappingVersions":{"type":"array","description":"The published mapping version each stream uses in this run, fixed when the run starts executing. Version `0` means that the stream has no published mappings. The field is absent while the run is `QUEUED`, on a dry run of the draft mappings, and on runs recorded before it existed.","items":{"type":"object","properties":{"streamId":{"type":"string","format":"uuid","description":"The stream identifier."},"version":{"type":"integer","description":"The published mapping version the stream uses."}}}}}}}}}
```

## The ImportRunStream object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportRunStream":{"title":"Run stream progress","type":"object","description":"The per-stream progress within a run.","properties":{"id":{"type":"string","format":"uuid","description":"The run-stream identifier."},"runId":{"type":"string","format":"uuid","description":"The run this progress belongs to."},"streamId":{"type":"string","format":"uuid","description":"The stream this progress belongs to."},"streamName":{"type":"string","description":"The stream name."},"status":{"type":"string","enum":["RUNNING","SUCCEEDED","PARTIAL","FAILED","ABORTED","CANCELLED"],"description":"The stream's status within the run. `ABORTED` means the service refused to run the stream because of its configuration, for example because its mappings have never been published. It indicates a configuration problem to fix. The `message` field gives the reason. `CANCELLED` means the run was cancelled while the stream was running."},"recordsRead":{"type":"integer","description":"Records read for this stream. The counters reconcile: `recordsRead` = created + updated + skipped + unresolvedParents + deleted + failed + collapsed + embedded."},"created":{"type":"integer","description":"Records created."},"updated":{"type":"integer","description":"Records updated."},"skipped":{"type":"integer","description":"Records skipped."},"failed":{"type":"integer","description":"Records that failed."},"deleted":{"type":"integer","description":"Records deleted."},"duplicateKeys":{"type":"integer","description":"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."},"unresolvedParents":{"type":"integer","description":"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."},"collapsed":{"type":"integer","description":"Source rows that repeated a key already present in the same batch. They are merged before the write, last row wins, and counted here — so the report adds up however the source feed is batched. A repeat in a *later* batch is written again and counted as created or updated instead; `duplicateKeys` is the signal for a feed that is not unique on its key."},"embedded":{"type":"integer","description":"Child records an `EMBED` composite child handed to its parent, which the parent then wrote inside its own instance. One write of the parent covers them all, so they are never counted as created or updated (that would count each line as an instance) and never as skipped (which means \"already up to date\"). If the parent turned out to be unchanged, failed, or absent, these are settled onto `skipped`, `failed`, or `unresolvedParents` once the parent's pass completes."},"message":{"type":"string","description":"A per-stream status message.\n\nWhen a run of a file-based stream finds no file waiting, the message starts with `No file was\nwaiting, so nothing was imported`. If the latest file in the stream's history failed, the message\nnames that file and suggests queuing it again. Otherwise, it suggests uploading a file to the\nstream's queue first. This message is not set for a dry run, for a retry, or for a stream whose\nconnection reads its file from a file URL."},"filesRead":{"type":"array","items":{"type":"string"},"description":"For a file-based source, the file locators this stream actually read, in the order it read them. Recorded so a retry re-reads exactly the same bytes: the file behind a locator can be replaced by a later drop, and re-running against a different file would report a clean success having repaired nothing."},"fileNames":{"type":"object","additionalProperties":{"type":"string"},"description":"The display name of each locator in `filesRead`, keyed by locator. A file is addressed by an opaque id, so the name is carried beside it rather than derived from it."},"capSkipped":{"type":"boolean","description":"True when the tenant's licensed `maxRecordsPerEntity` was reached and the remaining records were read but not written. They are counted as `skipped` and the stream is `PARTIAL`: the data is not lost, but it is not imported either until the limit is raised. See the license endpoint."},"keylessSeen":{"type":"boolean","description":"True when at least one source record had no value in its key column. Such a record is counted as both read and failed and is reported under error code `NO_KEY` — the import does not invent a key, because a synthesised one collides across records and changes whenever the record does."},"sweep":{"type":"boolean","description":"True for the extra row produced by the unresolved-parent sweep, which re-fetches the parents a composite child could not find and then re-reads their lines. A child's sweep row is folded into its original row and removed; a parent's sweep row remains, because its reads are genuinely new. Treat a row with this flag as a repair pass, not as a second stream."}}}}}}
```

## The RunDetail object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"RunDetail":{"title":"Run detail","type":"object","description":"A run together with its per-stream progress.","properties":{"run":{"$ref":"#/components/schemas/ImportRun"},"streams":{"type":"array","description":"The per-stream progress.","items":{"$ref":"#/components/schemas/ImportRunStream"}}}},"ImportRun":{"title":"Run","type":"object","description":"An import run and its reconciled counters.","properties":{"id":{"type":"string","format":"uuid","description":"The run identifier."},"configId":{"type":"string","format":"uuid","description":"The configuration the run belongs to."},"tenant":{"type":"string","description":"The owning tenant."},"trigger":{"type":"string","enum":["MANUAL","SCHEDULED","RETRY"],"description":"What triggered the run. Possible values:\n\n* `MANUAL` – triggered with the run operation.\n* `SCHEDULED` – started by the configuration's schedule.\n* `RETRY` – created by retrying the failed records of an earlier run. `retryOfRunId` names that run."},"dryRunSample":{"type":"array","description":"Dry-run only. A sample of the mapped records that would be written, so the mapping can be previewed without a real import. Absent on normal runs. Each stream is sampled separately, up to the `sampleSize` set in the run request. A parent stream's records include the records of its composite child streams that have `childStrategy` set to `EMBED` or `PATCH`. Those child records appear in the parent attribute named by the child stream's `embedAttribute`, as a real import writes them. Only child records inside the child stream's own sample are included, so a sampled parent record can show fewer child records than the source contains for that parent, or none. Child records are also sampled under their own stream.","items":{"type":"object","properties":{"stream":{"type":"string","description":"The stream that produced the sample record."},"targetType":{"type":"string","description":"The resolved target type the record would be written to."},"key":{"type":"string","description":"The record's natural/deterministic key."},"fields":{"type":"object","additionalProperties":true,"description":"The mapped target fields that would be written."}}}},"origin":{"type":"string","description":"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."},"status":{"type":"string","enum":["QUEUED","RUNNING","RESUMABLE","SUCCEEDED","PARTIAL","FAILED","CANCELLED","ABORTED"],"description":"The run status. Possible values:\n\n* `QUEUED` – the run waits to start. Nothing has been read yet, and the run has no per-stream\n  progress. `queueWaitingFor` says what the run waits for.\n* `RUNNING` – the run is executing.\n* `RESUMABLE` – the run was interrupted, for example by a service restart, and resumes automatically\n  from its last checkpoint. It is not a final status.\n* `SUCCEEDED` – the run finished, and every record was processed.\n* `PARTIAL` – the run finished, but not completely: some records failed, a limit skipped records,\n  or a stream was not run. The `message` field and the per-stream progress give the details.\n* `FAILED` – the run stopped because of an error.\n* `CANCELLED` – the run was cancelled.\n* `ABORTED` – the service refused to start the run because of the import configuration, for example\n  mappings that have never been published or a changed target schema. Nothing was read or written."},"mode":{"type":"string","enum":["FULL","DELTA"],"description":"The run mode."},"startedAt":{"type":"string","format":"date-time","description":"When the run was requested. If the run was queued first, it began executing later, at `executionStartedAt`."},"executionStartedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the run began executing. Equal to `startedAt`, or later by the time the run spent in the queue. `null` while the run is `QUEUED`, and on runs recorded before the field existed."},"finishedAt":{"type":"string","format":"date-time","description":"When the run finished."},"queuePosition":{"type":"integer","minimum":1,"description":"`QUEUED` runs only. The run's position among the queued runs that can start, where `1` starts next. Runs of all tenants share the queue, and a tenant with fewer runs executing goes first. The value is approximate, because the queue changes while you read it. The field is absent when the run is not queued, when it waits for something other than a worker, or when the service has not yet calculated it."},"queueWaitingFor":{"type":"string","enum":["WORKER","PREVIOUS_RUN","TENANT_LIMIT"],"description":"`QUEUED` runs only. What the run waits for. Possible values:\n\n* `WORKER` – the run waits for a free worker. `queuePosition` gives its place in the queue.\n* `PREVIOUS_RUN` – the run waits for the configuration's current run to finish.\n* `TENANT_LIMIT` – the run waits for one of the tenant's runs to finish, because\n  `maxConcurrentImports` runs are already executing.\n\nThe field is absent when the run is not queued, or when the service has not yet calculated it."},"supersededRequests":{"type":"integer","description":"The number of later scheduled run requests that were added to this run while it was queued. A configuration has at most one queued run, so a scheduled request that arrives while a real run of the whole configuration is queued does not queue a second run."},"lastRequestedAt":{"type":"string","format":"date-time","description":"When the latest scheduled run request counted in `supersededRequests` was made. Absent when `supersededRequests` is `0`."},"recordsRead":{"type":"integer","description":"Records read. The counters reconcile: `recordsRead` = created + updated + skipped + unresolvedParents + deleted + failed + collapsed + embedded. A client that sums only some of them will not balance."},"created":{"type":"integer","description":"Records created."},"updated":{"type":"integer","description":"Records updated."},"skipped":{"type":"integer","description":"Records skipped because they were unchanged."},"failed":{"type":"integer","description":"Records that failed."},"deleted":{"type":"integer","description":"Records deleted."},"duplicateKeys":{"type":"integer","description":"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."},"unresolvedParents":{"type":"integer","description":"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."},"collapsed":{"type":"integer","description":"Source rows that repeated a key already present in the same batch. They are merged before the write, last row wins, and counted here — so the report adds up however the source feed is batched. A repeat in a *later* batch is written again and counted as created or updated instead; `duplicateKeys` is the signal for a feed that is not unique on its key."},"embedded":{"type":"integer","description":"Child records an `EMBED` composite child handed to its parent, which the parent then wrote inside its own instance. One write of the parent covers them all, so they are never counted as created or updated (that would count each line as an instance) and never as skipped (which means \"already up to date\"). If the parent turned out to be unchanged, failed, or absent, these are settled onto `skipped`, `failed`, or `unresolvedParents` once the parent's pass completes."},"message":{"type":"string","description":"A terminal status message, typically set on failure."},"streamIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The streams the run was asked to execute, as sent in `streamIds` when it was triggered. Absent when the run executes every stream of the configuration."},"retryOfRunId":{"type":"string","format":"uuid","description":"When the run retries another run's failed records, the identifier of that original run."},"force":{"type":"boolean","description":"Whether the run rewrote every record, bypassing the skip-if-unchanged check."},"dryRun":{"type":"boolean","description":"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."},"cancelRequested":{"type":"boolean","description":"Whether cancellation has been requested for a run that is still finishing."},"dryRunSampleSize":{"type":"integer","description":"For a dry run, how many mapped records were kept as a sample."},"dryRunPublished":{"type":"boolean","description":"Dry-run only. Whether the dry run used the published mappings (`true`) or the draft mappings (`false`)."},"mappingVersions":{"type":"array","description":"The published mapping version each stream uses in this run, fixed when the run starts executing. Version `0` means that the stream has no published mappings. The field is absent while the run is `QUEUED`, on a dry run of the draft mappings, and on runs recorded before it existed.","items":{"type":"object","properties":{"streamId":{"type":"string","format":"uuid","description":"The stream identifier."},"version":{"type":"integer","description":"The published mapping version the stream uses."}}}}}},"ImportRunStream":{"title":"Run stream progress","type":"object","description":"The per-stream progress within a run.","properties":{"id":{"type":"string","format":"uuid","description":"The run-stream identifier."},"runId":{"type":"string","format":"uuid","description":"The run this progress belongs to."},"streamId":{"type":"string","format":"uuid","description":"The stream this progress belongs to."},"streamName":{"type":"string","description":"The stream name."},"status":{"type":"string","enum":["RUNNING","SUCCEEDED","PARTIAL","FAILED","ABORTED","CANCELLED"],"description":"The stream's status within the run. `ABORTED` means the service refused to run the stream because of its configuration, for example because its mappings have never been published. It indicates a configuration problem to fix. The `message` field gives the reason. `CANCELLED` means the run was cancelled while the stream was running."},"recordsRead":{"type":"integer","description":"Records read for this stream. The counters reconcile: `recordsRead` = created + updated + skipped + unresolvedParents + deleted + failed + collapsed + embedded."},"created":{"type":"integer","description":"Records created."},"updated":{"type":"integer","description":"Records updated."},"skipped":{"type":"integer","description":"Records skipped."},"failed":{"type":"integer","description":"Records that failed."},"deleted":{"type":"integer","description":"Records deleted."},"duplicateKeys":{"type":"integer","description":"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."},"unresolvedParents":{"type":"integer","description":"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."},"collapsed":{"type":"integer","description":"Source rows that repeated a key already present in the same batch. They are merged before the write, last row wins, and counted here — so the report adds up however the source feed is batched. A repeat in a *later* batch is written again and counted as created or updated instead; `duplicateKeys` is the signal for a feed that is not unique on its key."},"embedded":{"type":"integer","description":"Child records an `EMBED` composite child handed to its parent, which the parent then wrote inside its own instance. One write of the parent covers them all, so they are never counted as created or updated (that would count each line as an instance) and never as skipped (which means \"already up to date\"). If the parent turned out to be unchanged, failed, or absent, these are settled onto `skipped`, `failed`, or `unresolvedParents` once the parent's pass completes."},"message":{"type":"string","description":"A per-stream status message.\n\nWhen a run of a file-based stream finds no file waiting, the message starts with `No file was\nwaiting, so nothing was imported`. If the latest file in the stream's history failed, the message\nnames that file and suggests queuing it again. Otherwise, it suggests uploading a file to the\nstream's queue first. This message is not set for a dry run, for a retry, or for a stream whose\nconnection reads its file from a file URL."},"filesRead":{"type":"array","items":{"type":"string"},"description":"For a file-based source, the file locators this stream actually read, in the order it read them. Recorded so a retry re-reads exactly the same bytes: the file behind a locator can be replaced by a later drop, and re-running against a different file would report a clean success having repaired nothing."},"fileNames":{"type":"object","additionalProperties":{"type":"string"},"description":"The display name of each locator in `filesRead`, keyed by locator. A file is addressed by an opaque id, so the name is carried beside it rather than derived from it."},"capSkipped":{"type":"boolean","description":"True when the tenant's licensed `maxRecordsPerEntity` was reached and the remaining records were read but not written. They are counted as `skipped` and the stream is `PARTIAL`: the data is not lost, but it is not imported either until the limit is raised. See the license endpoint."},"keylessSeen":{"type":"boolean","description":"True when at least one source record had no value in its key column. Such a record is counted as both read and failed and is reported under error code `NO_KEY` — the import does not invent a key, because a synthesised one collides across records and changes whenever the record does."},"sweep":{"type":"boolean","description":"True for the extra row produced by the unresolved-parent sweep, which re-fetches the parents a composite child could not find and then re-reads their lines. A child's sweep row is folded into its original row and removed; a parent's sweep row remains, because its reads are genuinely new. Treat a row with this flag as a repair pass, not as a second stream."}}}}}}
```

## The CancelResult object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"CancelResult":{"title":"Cancellation result","type":"object","description":"The outcome of a cancellation request.","properties":{"runId":{"type":"string","format":"uuid","description":"The run the cancellation targeted."},"force":{"type":"boolean","description":"Whether a hard stop was requested."},"accepted":{"type":"boolean","description":"Whether the cancellation was accepted. `false` when the run does not exist, has already finished, or has the `RESUMABLE` status and `force` was not set."},"cancelRequested":{"type":"boolean","deprecated":true,"description":"The same value as `accepted`. Kept for clients written against an earlier response. Use `accepted`."}}}}}}
```

## The ErrorRecord object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ErrorRecord":{"title":"Error record","type":"object","description":"A single error recorded during a run.","properties":{"id":{"type":"string","format":"uuid","description":"The error identifier."},"runId":{"type":"string","format":"uuid","description":"The run the error occurred in."},"streamId":{"type":"string","format":"uuid","description":"The stream the error occurred in."},"naturalKey":{"type":"string","description":"The source natural key of the offending record."},"targetEntity":{"type":"string","description":"The target writer the record was bound for."},"stage":{"type":"string","enum":["EXTRACT","MAP","VALIDATE","UPSERT"],"description":"The pipeline stage the error occurred in. Possible values:\n\n* `EXTRACT` – reading records from the source.\n* `MAP` – applying the field mappings.\n* `VALIDATE` – validating the mapped record before the write.\n* `UPSERT` – writing to the target."},"errorCode":{"type":"string","description":"A machine-readable error code:\n\n* `VALIDATION` – the mapped record failed validation before any write was attempted.\n* `NO_KEY` – the record's key column was empty, so it cannot be identified.\n* `UPSERT` – the target rejected the write.\n* `CONFIGURATION` – something to change in the import's own configuration, not a fault: a\n  missing base URL, refused credentials, an unknown path, a stream that names no parent.\n* `EXTERNAL_SYSTEM` – another system answered with an error, for example the source returning\n  5xx or a source-side extraction failure.\n* `MERGE`, `PATCH_EMBED` – a composite merge or an embed patch onto the parent failed.\n* `NO_LINKING_VALUE` – a composite child row carried no value in its linking field.\n* `MARKER_DELETE`, `TOMBSTONE_DELETE`, `TOMBSTONE_NO_KEY` – a delete detected by a status\n  marker or a tombstone record could not be applied.\n* `REJECTED_BY_SOURCE` – the source rejected a single record because of its data, for example a\n  delimited-file row whose array has more elements than `sourceDataset.arrays.maxElements`. That\n  record is not imported, but the other records are; `message` names the column, its number of\n  elements, and the limit.\n* `FAN_OUT_REMOVE` – a `FAN_OUT` stream could not remove the objects its parent record no longer\n  lists. The next run that carries those records tries again.\n* `STREAM_ERROR` – the stream failed as a whole; the record-level detail is in `message`.\n\n`CONFIGURATION` and `EXTERNAL_SYSTEM` are reported as a plain sentence naming what to change.\nThey are not application faults and are not alerted on as such."},"message":{"type":"string","description":"A human-readable error message."},"payload":{"type":"object","additionalProperties":true,"description":"The source record that failed, as the service read it, when the error concerns one record. Absent for errors that concern the whole stream."},"createdAt":{"type":"string","format":"date-time","description":"When the error was recorded."}}}}}}
```

## The ImportedRecord object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportedRecord":{"title":"Imported record","type":"object","description":"A record that was imported. Holds keys and outcome; for composite parents it also holds the embedded child arrays.","properties":{"id":{"type":"string","format":"uuid","description":"The imported-record identifier."},"configId":{"type":"string","format":"uuid","description":"The configuration the record belongs to."},"streamId":{"type":"string","format":"uuid","description":"The stream that produced the record."},"runId":{"type":"string","format":"uuid","description":"The run that last touched the record."},"targetEntity":{"type":"string","description":"The target writer code."},"targetType":{"type":"string","description":"The target type."},"naturalKey":{"type":"string","description":"The source natural key."},"targetId":{"type":"string","description":"The deterministic Emporix instance ID the record was written under. It's derived from the natural key and allows the record to be located in the target."},"fields":{"type":"object","description":"The stored fields."},"outcome":{"type":"string","description":"The last outcome, one of `UPSERTED`, `DELETED`, `FAILED`, or `DRY_RUN`."},"importedAt":{"type":"string","format":"date-time","description":"When the record was last imported."}}}}}}
```

## The Page object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"Page":{"title":"Page","type":"object","description":"Pagination metadata for a page of results.","properties":{"totalElements":{"type":"integer","description":"The total number of elements across all pages."},"totalPages":{"type":"integer","description":"The total number of pages."},"number":{"type":"integer","description":"The current zero-based page number."},"size":{"type":"integer","description":"The page size."}}}}}}
```

## The ImportRunPage object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportRunPage":{"title":"Run page","allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"content":{"type":"array","description":"The runs on this page.","items":{"$ref":"#/components/schemas/ImportRun"}}}}]},"Page":{"title":"Page","type":"object","description":"Pagination metadata for a page of results.","properties":{"totalElements":{"type":"integer","description":"The total number of elements across all pages."},"totalPages":{"type":"integer","description":"The total number of pages."},"number":{"type":"integer","description":"The current zero-based page number."},"size":{"type":"integer","description":"The page size."}}},"ImportRun":{"title":"Run","type":"object","description":"An import run and its reconciled counters.","properties":{"id":{"type":"string","format":"uuid","description":"The run identifier."},"configId":{"type":"string","format":"uuid","description":"The configuration the run belongs to."},"tenant":{"type":"string","description":"The owning tenant."},"trigger":{"type":"string","enum":["MANUAL","SCHEDULED","RETRY"],"description":"What triggered the run. Possible values:\n\n* `MANUAL` – triggered with the run operation.\n* `SCHEDULED` – started by the configuration's schedule.\n* `RETRY` – created by retrying the failed records of an earlier run. `retryOfRunId` names that run."},"dryRunSample":{"type":"array","description":"Dry-run only. A sample of the mapped records that would be written, so the mapping can be previewed without a real import. Absent on normal runs. Each stream is sampled separately, up to the `sampleSize` set in the run request. A parent stream's records include the records of its composite child streams that have `childStrategy` set to `EMBED` or `PATCH`. Those child records appear in the parent attribute named by the child stream's `embedAttribute`, as a real import writes them. Only child records inside the child stream's own sample are included, so a sampled parent record can show fewer child records than the source contains for that parent, or none. Child records are also sampled under their own stream.","items":{"type":"object","properties":{"stream":{"type":"string","description":"The stream that produced the sample record."},"targetType":{"type":"string","description":"The resolved target type the record would be written to."},"key":{"type":"string","description":"The record's natural/deterministic key."},"fields":{"type":"object","additionalProperties":true,"description":"The mapped target fields that would be written."}}}},"origin":{"type":"string","description":"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."},"status":{"type":"string","enum":["QUEUED","RUNNING","RESUMABLE","SUCCEEDED","PARTIAL","FAILED","CANCELLED","ABORTED"],"description":"The run status. Possible values:\n\n* `QUEUED` – the run waits to start. Nothing has been read yet, and the run has no per-stream\n  progress. `queueWaitingFor` says what the run waits for.\n* `RUNNING` – the run is executing.\n* `RESUMABLE` – the run was interrupted, for example by a service restart, and resumes automatically\n  from its last checkpoint. It is not a final status.\n* `SUCCEEDED` – the run finished, and every record was processed.\n* `PARTIAL` – the run finished, but not completely: some records failed, a limit skipped records,\n  or a stream was not run. The `message` field and the per-stream progress give the details.\n* `FAILED` – the run stopped because of an error.\n* `CANCELLED` – the run was cancelled.\n* `ABORTED` – the service refused to start the run because of the import configuration, for example\n  mappings that have never been published or a changed target schema. Nothing was read or written."},"mode":{"type":"string","enum":["FULL","DELTA"],"description":"The run mode."},"startedAt":{"type":"string","format":"date-time","description":"When the run was requested. If the run was queued first, it began executing later, at `executionStartedAt`."},"executionStartedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the run began executing. Equal to `startedAt`, or later by the time the run spent in the queue. `null` while the run is `QUEUED`, and on runs recorded before the field existed."},"finishedAt":{"type":"string","format":"date-time","description":"When the run finished."},"queuePosition":{"type":"integer","minimum":1,"description":"`QUEUED` runs only. The run's position among the queued runs that can start, where `1` starts next. Runs of all tenants share the queue, and a tenant with fewer runs executing goes first. The value is approximate, because the queue changes while you read it. The field is absent when the run is not queued, when it waits for something other than a worker, or when the service has not yet calculated it."},"queueWaitingFor":{"type":"string","enum":["WORKER","PREVIOUS_RUN","TENANT_LIMIT"],"description":"`QUEUED` runs only. What the run waits for. Possible values:\n\n* `WORKER` – the run waits for a free worker. `queuePosition` gives its place in the queue.\n* `PREVIOUS_RUN` – the run waits for the configuration's current run to finish.\n* `TENANT_LIMIT` – the run waits for one of the tenant's runs to finish, because\n  `maxConcurrentImports` runs are already executing.\n\nThe field is absent when the run is not queued, or when the service has not yet calculated it."},"supersededRequests":{"type":"integer","description":"The number of later scheduled run requests that were added to this run while it was queued. A configuration has at most one queued run, so a scheduled request that arrives while a real run of the whole configuration is queued does not queue a second run."},"lastRequestedAt":{"type":"string","format":"date-time","description":"When the latest scheduled run request counted in `supersededRequests` was made. Absent when `supersededRequests` is `0`."},"recordsRead":{"type":"integer","description":"Records read. The counters reconcile: `recordsRead` = created + updated + skipped + unresolvedParents + deleted + failed + collapsed + embedded. A client that sums only some of them will not balance."},"created":{"type":"integer","description":"Records created."},"updated":{"type":"integer","description":"Records updated."},"skipped":{"type":"integer","description":"Records skipped because they were unchanged."},"failed":{"type":"integer","description":"Records that failed."},"deleted":{"type":"integer","description":"Records deleted."},"duplicateKeys":{"type":"integer","description":"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."},"unresolvedParents":{"type":"integer","description":"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."},"collapsed":{"type":"integer","description":"Source rows that repeated a key already present in the same batch. They are merged before the write, last row wins, and counted here — so the report adds up however the source feed is batched. A repeat in a *later* batch is written again and counted as created or updated instead; `duplicateKeys` is the signal for a feed that is not unique on its key."},"embedded":{"type":"integer","description":"Child records an `EMBED` composite child handed to its parent, which the parent then wrote inside its own instance. One write of the parent covers them all, so they are never counted as created or updated (that would count each line as an instance) and never as skipped (which means \"already up to date\"). If the parent turned out to be unchanged, failed, or absent, these are settled onto `skipped`, `failed`, or `unresolvedParents` once the parent's pass completes."},"message":{"type":"string","description":"A terminal status message, typically set on failure."},"streamIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The streams the run was asked to execute, as sent in `streamIds` when it was triggered. Absent when the run executes every stream of the configuration."},"retryOfRunId":{"type":"string","format":"uuid","description":"When the run retries another run's failed records, the identifier of that original run."},"force":{"type":"boolean","description":"Whether the run rewrote every record, bypassing the skip-if-unchanged check."},"dryRun":{"type":"boolean","description":"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."},"cancelRequested":{"type":"boolean","description":"Whether cancellation has been requested for a run that is still finishing."},"dryRunSampleSize":{"type":"integer","description":"For a dry run, how many mapped records were kept as a sample."},"dryRunPublished":{"type":"boolean","description":"Dry-run only. Whether the dry run used the published mappings (`true`) or the draft mappings (`false`)."},"mappingVersions":{"type":"array","description":"The published mapping version each stream uses in this run, fixed when the run starts executing. Version `0` means that the stream has no published mappings. The field is absent while the run is `QUEUED`, on a dry run of the draft mappings, and on runs recorded before it existed.","items":{"type":"object","properties":{"streamId":{"type":"string","format":"uuid","description":"The stream identifier."},"version":{"type":"integer","description":"The published mapping version the stream uses."}}}}}}}}}
```

## The DiagnosticPage object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"DiagnosticPage":{"type":"object","description":"A page of diagnostic rows with metadata that indicates whether the response contains all recorded rows or only part of a capped sample. Use `recorded`, `cap`, and `sampleTruncated` to interpret the page. The run's counters show the total number of affected rows.","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/DiagnosticRecord"}},"returned":{"type":"integer","description":"How many rows this response contains."},"recorded":{"type":"integer","description":"How many rows were recorded in total for this scope."},"cap":{"type":"integer","description":"The per-stream, per-kind recording cap."},"sampleTruncated":{"type":"boolean","description":"Whether at least one stream reached the cap. When true, these rows are a sample, and the run's\nown counters show the total number of affected rows."},"note":{"type":"string","description":"A human-readable statement of what this response is."}}},"DiagnosticRecord":{"type":"object","description":"One row behind a feed-quality counter.","properties":{"id":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"streamId":{"type":"string","format":"uuid"},"streamName":{"type":"string","description":"The stream that recorded the row."},"kind":{"type":"string","enum":["UNRESOLVED_PARENT","REPEATED_KEY"],"description":"`UNRESOLVED_PARENT`: a child line whose parent instance did not exist when it was written.\n`REPEATED_KEY`: a source row whose natural key this run had already imported."},"naturalKey":{"type":"string","description":"The record's own natural key in the source."},"linkingField":{"type":"string","description":"`UNRESOLVED_PARENT` only. The field that points at the parent."},"linkingValue":{"type":"string","description":"`UNRESOLVED_PARENT` only. The parent key the line pointed at — the value to look up in the\nsource system."},"targetType":{"type":"string","description":"The target type the row was headed for."},"waitingLines":{"type":"integer","description":"`UNRESOLVED_PARENT` only. The number of child lines waiting for this parent."},"occurrence":{"type":"integer","description":"`REPEATED_KEY` only. How many times this key had already been seen in this run."},"createdAt":{"type":"string","format":"date-time"}}}}}}
```

## The DiagnosticRecord object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"DiagnosticRecord":{"type":"object","description":"One row behind a feed-quality counter.","properties":{"id":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"streamId":{"type":"string","format":"uuid"},"streamName":{"type":"string","description":"The stream that recorded the row."},"kind":{"type":"string","enum":["UNRESOLVED_PARENT","REPEATED_KEY"],"description":"`UNRESOLVED_PARENT`: a child line whose parent instance did not exist when it was written.\n`REPEATED_KEY`: a source row whose natural key this run had already imported."},"naturalKey":{"type":"string","description":"The record's own natural key in the source."},"linkingField":{"type":"string","description":"`UNRESOLVED_PARENT` only. The field that points at the parent."},"linkingValue":{"type":"string","description":"`UNRESOLVED_PARENT` only. The parent key the line pointed at — the value to look up in the\nsource system."},"targetType":{"type":"string","description":"The target type the row was headed for."},"waitingLines":{"type":"integer","description":"`UNRESOLVED_PARENT` only. The number of child lines waiting for this parent."},"occurrence":{"type":"integer","description":"`REPEATED_KEY` only. How many times this key had already been seen in this run."},"createdAt":{"type":"string","format":"date-time"}}}}}}
```

## The ErrorRecordPage object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ErrorRecordPage":{"title":"Error record page","allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"content":{"type":"array","description":"The error records on this page.","items":{"$ref":"#/components/schemas/ErrorRecord"}}}}]},"Page":{"title":"Page","type":"object","description":"Pagination metadata for a page of results.","properties":{"totalElements":{"type":"integer","description":"The total number of elements across all pages."},"totalPages":{"type":"integer","description":"The total number of pages."},"number":{"type":"integer","description":"The current zero-based page number."},"size":{"type":"integer","description":"The page size."}}},"ErrorRecord":{"title":"Error record","type":"object","description":"A single error recorded during a run.","properties":{"id":{"type":"string","format":"uuid","description":"The error identifier."},"runId":{"type":"string","format":"uuid","description":"The run the error occurred in."},"streamId":{"type":"string","format":"uuid","description":"The stream the error occurred in."},"naturalKey":{"type":"string","description":"The source natural key of the offending record."},"targetEntity":{"type":"string","description":"The target writer the record was bound for."},"stage":{"type":"string","enum":["EXTRACT","MAP","VALIDATE","UPSERT"],"description":"The pipeline stage the error occurred in. Possible values:\n\n* `EXTRACT` – reading records from the source.\n* `MAP` – applying the field mappings.\n* `VALIDATE` – validating the mapped record before the write.\n* `UPSERT` – writing to the target."},"errorCode":{"type":"string","description":"A machine-readable error code:\n\n* `VALIDATION` – the mapped record failed validation before any write was attempted.\n* `NO_KEY` – the record's key column was empty, so it cannot be identified.\n* `UPSERT` – the target rejected the write.\n* `CONFIGURATION` – something to change in the import's own configuration, not a fault: a\n  missing base URL, refused credentials, an unknown path, a stream that names no parent.\n* `EXTERNAL_SYSTEM` – another system answered with an error, for example the source returning\n  5xx or a source-side extraction failure.\n* `MERGE`, `PATCH_EMBED` – a composite merge or an embed patch onto the parent failed.\n* `NO_LINKING_VALUE` – a composite child row carried no value in its linking field.\n* `MARKER_DELETE`, `TOMBSTONE_DELETE`, `TOMBSTONE_NO_KEY` – a delete detected by a status\n  marker or a tombstone record could not be applied.\n* `REJECTED_BY_SOURCE` – the source rejected a single record because of its data, for example a\n  delimited-file row whose array has more elements than `sourceDataset.arrays.maxElements`. That\n  record is not imported, but the other records are; `message` names the column, its number of\n  elements, and the limit.\n* `FAN_OUT_REMOVE` – a `FAN_OUT` stream could not remove the objects its parent record no longer\n  lists. The next run that carries those records tries again.\n* `STREAM_ERROR` – the stream failed as a whole; the record-level detail is in `message`.\n\n`CONFIGURATION` and `EXTERNAL_SYSTEM` are reported as a plain sentence naming what to change.\nThey are not application faults and are not alerted on as such."},"message":{"type":"string","description":"A human-readable error message."},"payload":{"type":"object","additionalProperties":true,"description":"The source record that failed, as the service read it, when the error concerns one record. Absent for errors that concern the whole stream."},"createdAt":{"type":"string","format":"date-time","description":"When the error was recorded."}}}}}}
```

## The ImportedRecordPage object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportedRecordPage":{"title":"Imported record page","allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"content":{"type":"array","description":"The imported records on this page.","items":{"$ref":"#/components/schemas/ImportedRecord"}}}}]},"Page":{"title":"Page","type":"object","description":"Pagination metadata for a page of results.","properties":{"totalElements":{"type":"integer","description":"The total number of elements across all pages."},"totalPages":{"type":"integer","description":"The total number of pages."},"number":{"type":"integer","description":"The current zero-based page number."},"size":{"type":"integer","description":"The page size."}}},"ImportedRecord":{"title":"Imported record","type":"object","description":"A record that was imported. Holds keys and outcome; for composite parents it also holds the embedded child arrays.","properties":{"id":{"type":"string","format":"uuid","description":"The imported-record identifier."},"configId":{"type":"string","format":"uuid","description":"The configuration the record belongs to."},"streamId":{"type":"string","format":"uuid","description":"The stream that produced the record."},"runId":{"type":"string","format":"uuid","description":"The run that last touched the record."},"targetEntity":{"type":"string","description":"The target writer code."},"targetType":{"type":"string","description":"The target type."},"naturalKey":{"type":"string","description":"The source natural key."},"targetId":{"type":"string","description":"The deterministic Emporix instance ID the record was written under. It's derived from the natural key and allows the record to be located in the target."},"fields":{"type":"object","description":"The stored fields."},"outcome":{"type":"string","description":"The last outcome, one of `UPSERTED`, `DELETED`, `FAILED`, or `DRY_RUN`."},"importedAt":{"type":"string","format":"date-time","description":"When the record was last imported."}}}}}}
```

## The HealthThresholds object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"HealthThresholds":{"title":"Health thresholds","type":"object","description":"The limits that decide whether a stream is reported as `GREEN`, `AMBER`, or `RED`. Each field is optional and resolves independently. An unset field falls back through the hierarchy, from the most specific level to the least specific: stream, configuration, tenant, then the built-in default.","properties":{"failureRatioAmber":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `AMBER`."},"failureRatioRed":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `RED`."},"staleAmberHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `AMBER` when the data's age reaches or exceeds this threshold."},"staleRedHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `RED` when the data's age reaches or exceeds this threshold."},"failedRunIsRed":{"type":"boolean","description":"Whether a failed most-recent run makes the stream `RED` regardless of the other limits."}}}}}}
```

## The HealthSettings object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"HealthSettings":{"title":"Tenant health thresholds","type":"object","description":"The tenant-wide thresholds, together with the built-in defaults they fall back to.","properties":{"thresholds":{"$ref":"#/components/schemas/HealthThresholds"},"builtInDefaults":{"$ref":"#/components/schemas/HealthThresholds"}}},"HealthThresholds":{"title":"Health thresholds","type":"object","description":"The limits that decide whether a stream is reported as `GREEN`, `AMBER`, or `RED`. Each field is optional and resolves independently. An unset field falls back through the hierarchy, from the most specific level to the least specific: stream, configuration, tenant, then the built-in default.","properties":{"failureRatioAmber":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `AMBER`."},"failureRatioRed":{"type":"number","format":"double","description":"The share of failed records (0..1) at or above which the stream is `RED`."},"staleAmberHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `AMBER` when the data's age reaches or exceeds this threshold."},"staleRedHours":{"type":"integer","description":"The age threshold, in hours, for the stream's newest data. The stream is `RED` when the data's age reaches or exceeds this threshold."},"failedRunIsRed":{"type":"boolean","description":"Whether a failed most-recent run makes the stream `RED` regardless of the other limits."}}}}}}
```

## The JobGroup object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"JobGroup":{"title":"Job group","type":"object","description":"A named set of import configurations, used to scope the import statistics.","properties":{"id":{"type":"string","format":"uuid","description":"The job group identifier."},"name":{"type":"string","description":"The job group name. Unique within the tenant."},"configIds":{"type":"array","description":"The configurations in the group.","items":{"type":"string","format":"uuid"}},"createdAt":{"type":"string","format":"date-time","description":"When the group was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the group was last changed."}}}}}}
```

## The ImportLicense object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportLicense":{"title":"Import limits","type":"object","description":"The import limits that apply to the tenant.","properties":{"maxRecordsPerEntity":{"type":"integer","description":"The maximum number of records a single run may write per target type. Records beyond the limit are skipped and the run finishes as `PARTIAL`."},"maxConcurrentImports":{"type":"integer","description":"The maximum number of runs that can execute at once for the tenant. A run requested beyond this limit is not rejected. It waits in the `QUEUED` status until one of the tenant's runs finishes."},"batchSize":{"type":"integer","description":"The number of records written to the target per request."},"workers":{"type":"integer","description":"The number of target writes performed in parallel."}}}}}}
```

## The ImportStatsSummary object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStatsSummary":{"title":"Statistics summary","type":"object","description":"Headline totals for the window. Rates are fractions between 0 and 1.","properties":{"totalRuns":{"type":"integer","description":"The number of runs started in the window."},"succeeded":{"type":"integer","description":"The number of runs that finished successfully."},"partial":{"type":"integer","description":"The number of runs that finished with some records failing."},"failed":{"type":"integer","description":"The number of runs that failed."},"cancelled":{"type":"integer","description":"The number of runs that were cancelled."},"aborted":{"type":"integer","description":"The number of runs the service refused to run because of their configuration (`ABORTED`)."},"recordsRead":{"type":"integer","description":"The number of source records read."},"created":{"type":"integer","description":"The number of target objects created."},"updated":{"type":"integer","description":"The number of target objects updated."},"skipped":{"type":"integer","description":"The number of records skipped because nothing had changed."},"deleted":{"type":"integer","description":"The number of target objects deleted."},"failedRecords":{"type":"integer","description":"The number of records that could not be imported."},"successRate":{"type":"number","format":"double","description":"The share of runs that finished successfully."},"failureRate":{"type":"number","format":"double","description":"The share of records that failed."},"deletionRate":{"type":"number","format":"double","description":"The share of processed records that resulted in a deletion."},"skipRate":{"type":"number","format":"double","description":"The share of records skipped as unchanged."},"avgRunDurationSec":{"type":"number","format":"double","description":"The mean duration of a finished run, in seconds, measured from when the run began executing (`executionStartedAt`). Time spent in the queue is not counted."},"avgCreatedPerRun":{"type":"number","format":"double","description":"The mean number of objects created per run."},"avgUpdatedPerRun":{"type":"number","format":"double","description":"The mean number of objects updated per run."},"distinctEntities":{"type":"integer","description":"The number of distinct target objects currently held by the imports in scope."},"activeRuns":{"type":"integer","description":"The number of runs currently in the `QUEUED`, `RUNNING`, or `RESUMABLE` status. When you filter by `streamId`, queued runs are not counted, because they have not started any stream yet."}}}}}}
```

## The ImportStatsPoint object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStatsPoint":{"title":"Statistics time bucket","type":"object","description":"One bucket of the time series, in UTC.","properties":{"bucket":{"type":"string","format":"date-time","description":"The start of the bucket."},"runs":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"recordsRead":{"type":"integer"},"created":{"type":"integer"},"updated":{"type":"integer"},"deleted":{"type":"integer"},"skipped":{"type":"integer"},"failedRecords":{"type":"integer"}}}}}}
```

## The ImportStreamHealth object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStreamHealth":{"title":"Stream health","type":"object","description":"The health of one stream over the window, and the thresholds the verdict used.","properties":{"streamId":{"type":"string","format":"uuid"},"configId":{"type":"string","format":"uuid","description":"The configuration the stream belongs to."},"name":{"type":"string"},"targetType":{"type":"string","description":"The target type the stream writes to."},"lastRunStatus":{"type":"string","description":"The status of the stream's most recent run."},"lastRunAt":{"type":"string","format":"date-time"},"watermarkAgeSeconds":{"type":"integer","description":"The number of seconds since the stream last detected new data."},"failureRatio":{"type":"number","format":"double","description":"The share of the stream's records that failed in the window."},"health":{"type":"string","enum":["GREEN","AMBER","RED"],"description":"The stream's health verdict."},"thresholds":{"$ref":"#/components/schemas/ImportEffectiveThresholds"}}},"ImportEffectiveThresholds":{"title":"Effective thresholds","type":"object","description":"The threshold values the verdict was actually computed with, after resolving every level.","properties":{"failureRatioAmber":{"type":"number","format":"double"},"failureRatioRed":{"type":"number","format":"double"},"staleAmberHours":{"type":"integer"},"staleRedHours":{"type":"integer"},"failedRunIsRed":{"type":"boolean"},"customised":{"type":"boolean","description":"Whether any level overrides the built-in defaults."}}}}}}
```

## The ImportEffectiveThresholds object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportEffectiveThresholds":{"title":"Effective thresholds","type":"object","description":"The threshold values the verdict was actually computed with, after resolving every level.","properties":{"failureRatioAmber":{"type":"number","format":"double"},"failureRatioRed":{"type":"number","format":"double"},"staleAmberHours":{"type":"integer"},"staleRedHours":{"type":"integer"},"failedRunIsRed":{"type":"boolean"},"customised":{"type":"boolean","description":"Whether any level overrides the built-in defaults."}}}}}}
```

## The ImportStatsNamedCount object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStatsNamedCount":{"title":"Named count","type":"object","properties":{"streamId":{"type":"string","format":"uuid"},"name":{"type":"string"},"count":{"type":"integer"}}}}}}
```

## The ImportStatsErrorBucket object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStatsErrorBucket":{"title":"Error bucket","type":"object","description":"A count of errors sharing the same stage and code.","properties":{"stage":{"type":"string","description":"The pipeline stage the error occurred in."},"errorCode":{"type":"string"},"count":{"type":"integer"}}}}}}
```

## The ImportStreamChanges object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStreamChanges":{"title":"Stream changes","type":"object","description":"The counts of streams added and removed during the time window.","properties":{"added":{"type":"integer"},"removed":{"type":"integer"},"trackingSince":{"type":"string","format":"date-time","description":"When stream tracking began for the tenant. Streams created before this point are not counted, so a window reaching further back is not comparable."},"series":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string","format":"date-time"},"added":{"type":"integer"},"removed":{"type":"integer"}}}}}}}}}
```

## The ImportStats object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportStats":{"title":"Import statistics","type":"object","description":"Aggregated import metrics for the requested window and scope. A section that was not requested via the `sections` parameter is returned as `null`.","properties":{"summary":{"$ref":"#/components/schemas/ImportStatsSummary"},"series":{"type":"array","description":"Activity per time bucket, ordered oldest first and gap-free.","items":{"$ref":"#/components/schemas/ImportStatsPoint"}},"streamHealth":{"type":"array","description":"The health of each stream in scope.","items":{"$ref":"#/components/schemas/ImportStreamHealth"}},"topFailingStreams":{"type":"array","description":"The streams with the most errors during the time window, ordered by error count in descending order.","items":{"$ref":"#/components/schemas/ImportStatsNamedCount"}},"errorBreakdown":{"type":"array","description":"The most common errors in the window, grouped by stage and code.","items":{"$ref":"#/components/schemas/ImportStatsErrorBucket"}},"streamChanges":{"$ref":"#/components/schemas/ImportStreamChanges"},"sourceIssues":{"type":"array","description":"The source data does not match what the import process expects during the specified time window. These issues are not failures: the runs succeed, so they do not appear in pass/fail counters.","items":{"$ref":"#/components/schemas/ImportSourceIssue"}}}},"ImportStatsSummary":{"title":"Statistics summary","type":"object","description":"Headline totals for the window. Rates are fractions between 0 and 1.","properties":{"totalRuns":{"type":"integer","description":"The number of runs started in the window."},"succeeded":{"type":"integer","description":"The number of runs that finished successfully."},"partial":{"type":"integer","description":"The number of runs that finished with some records failing."},"failed":{"type":"integer","description":"The number of runs that failed."},"cancelled":{"type":"integer","description":"The number of runs that were cancelled."},"aborted":{"type":"integer","description":"The number of runs the service refused to run because of their configuration (`ABORTED`)."},"recordsRead":{"type":"integer","description":"The number of source records read."},"created":{"type":"integer","description":"The number of target objects created."},"updated":{"type":"integer","description":"The number of target objects updated."},"skipped":{"type":"integer","description":"The number of records skipped because nothing had changed."},"deleted":{"type":"integer","description":"The number of target objects deleted."},"failedRecords":{"type":"integer","description":"The number of records that could not be imported."},"successRate":{"type":"number","format":"double","description":"The share of runs that finished successfully."},"failureRate":{"type":"number","format":"double","description":"The share of records that failed."},"deletionRate":{"type":"number","format":"double","description":"The share of processed records that resulted in a deletion."},"skipRate":{"type":"number","format":"double","description":"The share of records skipped as unchanged."},"avgRunDurationSec":{"type":"number","format":"double","description":"The mean duration of a finished run, in seconds, measured from when the run began executing (`executionStartedAt`). Time spent in the queue is not counted."},"avgCreatedPerRun":{"type":"number","format":"double","description":"The mean number of objects created per run."},"avgUpdatedPerRun":{"type":"number","format":"double","description":"The mean number of objects updated per run."},"distinctEntities":{"type":"integer","description":"The number of distinct target objects currently held by the imports in scope."},"activeRuns":{"type":"integer","description":"The number of runs currently in the `QUEUED`, `RUNNING`, or `RESUMABLE` status. When you filter by `streamId`, queued runs are not counted, because they have not started any stream yet."}}},"ImportStatsPoint":{"title":"Statistics time bucket","type":"object","description":"One bucket of the time series, in UTC.","properties":{"bucket":{"type":"string","format":"date-time","description":"The start of the bucket."},"runs":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"recordsRead":{"type":"integer"},"created":{"type":"integer"},"updated":{"type":"integer"},"deleted":{"type":"integer"},"skipped":{"type":"integer"},"failedRecords":{"type":"integer"}}},"ImportStreamHealth":{"title":"Stream health","type":"object","description":"The health of one stream over the window, and the thresholds the verdict used.","properties":{"streamId":{"type":"string","format":"uuid"},"configId":{"type":"string","format":"uuid","description":"The configuration the stream belongs to."},"name":{"type":"string"},"targetType":{"type":"string","description":"The target type the stream writes to."},"lastRunStatus":{"type":"string","description":"The status of the stream's most recent run."},"lastRunAt":{"type":"string","format":"date-time"},"watermarkAgeSeconds":{"type":"integer","description":"The number of seconds since the stream last detected new data."},"failureRatio":{"type":"number","format":"double","description":"The share of the stream's records that failed in the window."},"health":{"type":"string","enum":["GREEN","AMBER","RED"],"description":"The stream's health verdict."},"thresholds":{"$ref":"#/components/schemas/ImportEffectiveThresholds"}}},"ImportEffectiveThresholds":{"title":"Effective thresholds","type":"object","description":"The threshold values the verdict was actually computed with, after resolving every level.","properties":{"failureRatioAmber":{"type":"number","format":"double"},"failureRatioRed":{"type":"number","format":"double"},"staleAmberHours":{"type":"integer"},"staleRedHours":{"type":"integer"},"failedRunIsRed":{"type":"boolean"},"customised":{"type":"boolean","description":"Whether any level overrides the built-in defaults."}}},"ImportStatsNamedCount":{"title":"Named count","type":"object","properties":{"streamId":{"type":"string","format":"uuid"},"name":{"type":"string"},"count":{"type":"integer"}}},"ImportStatsErrorBucket":{"title":"Error bucket","type":"object","description":"A count of errors sharing the same stage and code.","properties":{"stage":{"type":"string","description":"The pipeline stage the error occurred in."},"errorCode":{"type":"string"},"count":{"type":"integer"}}},"ImportStreamChanges":{"title":"Stream changes","type":"object","description":"The counts of streams added and removed during the time window.","properties":{"added":{"type":"integer"},"removed":{"type":"integer"},"trackingSince":{"type":"string","format":"date-time","description":"When stream tracking began for the tenant. Streams created before this point are not counted, so a window reaching further back is not comparable."},"series":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string","format":"date-time"},"added":{"type":"integer"},"removed":{"type":"integer"}}}}}},"ImportSourceIssue":{"type":"object","properties":{"streamId":{"type":"string","format":"uuid","description":"The stream the problem was observed on."},"configId":{"type":"string","format":"uuid","description":"The configuration that owns the stream."},"name":{"type":"string","description":"The stream name."},"duplicateKeys":{"type":"integer","description":"Source rows that repeat a key already imported in the same run. The import keeps the last row of each repeated key and discards earlier rows."},"unresolvedParents":{"type":"integer","description":"Child records that were not imported because their parent could not be found."}}}}}}
```

## The ImportSourceIssue object

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"components":{"schemas":{"ImportSourceIssue":{"type":"object","properties":{"streamId":{"type":"string","format":"uuid","description":"The stream the problem was observed on."},"configId":{"type":"string","format":"uuid","description":"The configuration that owns the stream."},"name":{"type":"string","description":"The stream name."},"duplicateKeys":{"type":"integer","description":"Source rows that repeat a key already imported in the same run. The import keeps the last row of each repeated key and discards earlier rows."},"unresolvedParents":{"type":"integer","description":"Child records that were not imported because their parent could not be found."}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.emporix.io/api-references/readme/api-reference-19/models.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
