> 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/streams.md).

# Streams

Read the streams of a configuration.

## Retrieving all streams of a configuration

> Retrieves the streams belonging to a configuration, ordered by \`seq\`.

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"tags":[{"name":"Streams","description":"Read the streams of a configuration."}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["importtool.import_trigger"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"importtool.import_trigger":"Needed to trigger, schedule, monitor, and cancel import runs; to manage a file-based stream's file queue; and to read configurations, streams, schedules, runs, and imported data."}}}}},"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."}}},"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"]}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"An unexpected error occurred in the service. The body is the framework's default error body, not the error schema of the other responses.","content":{"application/json":{"schema":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"When the error occurred."},"status":{"type":"integer","description":"The HTTP status code."},"error":{"type":"string","description":"The HTTP status reason phrase."},"path":{"type":"string","description":"The request path."}}}}}}}},"paths":{"/importtool/{tenant}/configs/{configId}/streams":{"get":{"summary":"Retrieving all streams of a configuration","description":"Retrieves the streams belonging to a configuration, ordered by `seq`.","operationId":"GET-importtool-list-streams","tags":["Streams"],"responses":{"200":{"description":"The request was successful. The streams are returned.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ImportStream"}}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}}}}}}
```

## Retrieving a stream

> Retrieves a single stream by its identifier.

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"tags":[{"name":"Streams","description":"Read the streams of a configuration."}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["importtool.import_trigger"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"importtool.import_trigger":"Needed to trigger, schedule, monitor, and cancel import runs; to manage a file-based stream's file queue; and to read configurations, streams, schedules, runs, and imported data."}}}}},"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."}}},"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"]}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"An unexpected error occurred in the service. The body is the framework's default error body, not the error schema of the other responses.","content":{"application/json":{"schema":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"When the error occurred."},"status":{"type":"integer","description":"The HTTP status code."},"error":{"type":"string","description":"The HTTP status reason phrase."},"path":{"type":"string","description":"The request path."}}}}}}}},"paths":{"/importtool/{tenant}/streams/{id}":{"get":{"summary":"Retrieving a stream","description":"Retrieves a single stream by its identifier.","operationId":"GET-importtool-get-stream","tags":["Streams"],"responses":{"200":{"description":"The request was successful. The stream is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportStream"}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}}}}}}
```

## Retrieving the stream run order

> Retrieves the order in which the configuration's streams run, and the dependencies behind that order.\
> \
> Dependencies between streams decide the order. The streams' \`seq\` values break ties.\
> \
> Dependencies come from five sources:\
> \
> \* an explicit dependency on another stream\
> \* a mapping that references a type another stream produces\
> \* a \`COMPOSITE\_CHILD\` stream with \`childStrategy\` set to \`EMBED\` – runs before the parent that embeds it\
> \* a \`COMPOSITE\_CHILD\` stream with \`childStrategy\` set to \`PATCH\`, or a \`COMPOSITE\_MERGE\` stream – run after the parent they update\
> \* a \`FAN\_OUT\` stream – runs after the parent whose records it reads\
> \
> Use this endpoint rather than calculating the order yourself. Mapping transformations add\
> dependencies that a single stream definition does not show. An order calculated without those\
> dependencies can differ from the order used at run time.

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"tags":[{"name":"Streams","description":"Read the streams of a configuration."}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["importtool.import_trigger"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"importtool.import_trigger":"Needed to trigger, schedule, monitor, and cancel import runs; to manage a file-based stream's file queue; and to read configurations, streams, schedules, runs, and imported data."}}}}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"An unexpected error occurred in the service. The body is the framework's default error body, not the error schema of the other responses.","content":{"application/json":{"schema":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"When the error occurred."},"status":{"type":"integer","description":"The HTTP status code."},"error":{"type":"string","description":"The HTTP status reason phrase."},"path":{"type":"string","description":"The request path."}}}}}}},"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"]}}},"paths":{"/importtool/{tenant}/configs/{configId}/stream-order":{"get":{"summary":"Retrieving the stream run order","description":"Retrieves the order in which the configuration's streams run, and the dependencies behind that order.\n\nDependencies between streams decide the order. The streams' `seq` values break ties.\n\nDependencies come from five sources:\n\n* an explicit dependency on another stream\n* a mapping that references a type another stream produces\n* a `COMPOSITE_CHILD` stream with `childStrategy` set to `EMBED` – runs before the parent that embeds it\n* a `COMPOSITE_CHILD` stream with `childStrategy` set to `PATCH`, or a `COMPOSITE_MERGE` stream – run after the parent they update\n* a `FAN_OUT` stream – runs after the parent whose records it reads\n\nUse this endpoint rather than calculating the order yourself. Mapping transformations add\ndependencies that a single stream definition does not show. An order calculated without those\ndependencies can differ from the order used at run time.","operationId":"GET-importtool-stream-order","tags":["Streams"],"responses":{"200":{"description":"The request was successful. The stream order is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"array","items":{"type":"string"},"description":"Stream names in the order they run."},"prereqs":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"For each stream name, the streams that must run before it. A stream with no dependencies has an empty list."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}}}}}}
```


---

# 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/streams.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.
