> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding asynchronous enrichment integrations

> Why request lifetime, execution identity, retained results, and destination writes need separate boundaries.

An enrichment integration connects several systems with different lifetimes.
Your application has a request or worker task. Deepline has an execution.
A provider has its own request or job. The destination has an operating record.
A timeout at one boundary does not establish the outcome at the others.

## Submission and completion are different events

Starting a Play can return a public run ID before work finishes. That identity
lets the application observe the same execution later. It is a durable handoff,
not evidence that the business result already exists.

For example, a signup handler can submit enrichment and end its HTTP response.
The Play may finish afterward. The application needs to connect the eventual
outcome to the original signup, rather than launch a new run each time its
worker restarts.

A synchronous wait is a convenience for the caller. Its timeout does not
cancel remote work. Explicit cancellation and observing its result are
separate operations.

## Recovering observation differs from replaying execution

Reading a known run asks what happened to existing work. Starting another run
asks for a new execution. A recovery design must preserve that distinction.

Direct tool calls have a caller-owned idempotency-key contract. Reusing a valid
key with the same request observes or replays the original execution; changing
the request can conflict. A Play's internal tool-call label is not that public
idempotency key.

Neither contract establishes exactly-once effects in every external provider.
An ambiguous provider outcome can remain unresolved. Independent Play cache
misses can execute again, while completed matching work can be reused.

## The response is an execution contract, not a universal data model

A run package distinguishes status, outputs, retained results, and datasets.
The compact status response is not an inline copy of every row. Dataset rows
and full retained results have their own retrieval paths.

Within tool results, the scrubbed provider response and declared extraction
contracts serve different needs. A declared getter is useful for a supported
semantic field. Provider-specific paths require the actual inspected response
shape, not an assumption that every provider nests data identically.

The application also needs a domain acceptance rule. A completed lookup with
no usable candidate can be a valid result, while a failed request needs a
separate failure path.

## One owner should apply the destination result

The Play can perform an authorized destination action, or the caller can apply
the final result. Both are viable designs. Having both write independently can
create duplicate work or conflicting state.

In the signup example, the application might own the customer profile while the
Play returns research. Another integration might let the Play update approved
CRM fields directly. The chosen design determines where idempotency,
verification, and reconciliation belong.

A callback is also an external action. Losing its response can create the same
uncertainty as any other write. Authentication and destination-supported
idempotency still matter even when the enrichment itself completed.

## Usage is another recorded outcome

An empty result does not imply zero usage. Some operations charge for requests,
validation, or accepted events, and a later call can be new work. The recorded
billing outcome is the evidence for a charge; an absent or pending usage record
is not proof that execution was free.

## Apply this understanding

* [Production Play integration](https://deepline.com/docs/sdk-v2/production-integration.md): persist IDs, resume observation, and verify writes.
* [Tool execution recovery](https://deepline.com/docs/sdk-v2/tool-execution-recovery.md): direct-call key and input rules.
* [HTTP and Python](https://deepline.com/docs/sdk-v2/http-and-python.md): raw response and polling examples.
* [Runtime API reference](https://deepline.com/docs/sdk-v2/api-reference.md): exact response contracts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.