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

# Streams

Read the streams of a configuration.

## Retrieving all streams of a configuration

> Retrieves the streams belonging to a configuration, ordered by sequence.

```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 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":"The target writer code, for example `emporix.customEntity`."},"targetType":{"type":"string","description":"The default target type (custom-entity type identifier)."},"mode":{"type":"string","enum":["STANDALONE","COMPOSITE_CHILD","COMPOSITE_MERGE"],"description":"How the stream contributes to the target."},"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 stream, the name of the stream it contributes to."},"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. `PATCH` changes only the mapped fields and preserves everything else; `REPLACE_PUT` replaces the whole object, so fields this import does not manage are cleared."},"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."}}},"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":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}}},"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":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/importtool/{tenant}/configs/{configId}/streams":{"get":{"summary":"Retrieving all streams of a configuration","description":"Retrieves the streams belonging to a configuration, ordered by sequence.","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, including its resolved target types.

```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 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":"The target writer code, for example `emporix.customEntity`."},"targetType":{"type":"string","description":"The default target type (custom-entity type identifier)."},"mode":{"type":"string","enum":["STANDALONE","COMPOSITE_CHILD","COMPOSITE_MERGE"],"description":"How the stream contributes to the target."},"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 stream, the name of the stream it contributes to."},"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. `PATCH` changes only the mapped fields and preserves everything else; `REPLACE_PUT` replaces the whole object, so fields this import does not manage are cleared."},"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."}}},"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":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}}},"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":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/importtool/{tenant}/streams/{id}":{"get":{"summary":"Retrieving a stream","description":"Retrieves a single stream by its identifier, including its resolved target types.","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. Sequence breaks ties.\
> \
> Dependencies come from four 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\
> \
> 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 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":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}},"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":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}}},"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. Sequence breaks ties.\n\nDependencies come from four 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\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-33/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.