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

# HTTP and Python

> Start and observe a saved or prebuilt Play from Python or any HTTP-capable runtime.

[Human guide: work with your agent →](https://deepline.com/docs/human/sdk-v2/http-and-python.md)

> [!NOTE]
>
> Invoke an admitted Play from Python and recover observation through its
> persisted run ID.

Use this path when your work starts in Python, a notebook, a scheduler, or a
backend that should not shell out to the CLI.

For a direct provider tool instead of a Play, see
[tool execution recovery](https://deepline.com/docs/sdk-v2/tool-execution-recovery.md) for the
`Idempotency-Key` header and exact-key lookup endpoint.

Python does not author `.play.ts` files. It calls a saved or Prebuilt Play over
HTTP, receives a durable run ID, and observes that same run until terminal.

## Run the maintained Python caller

The repository example is `docs-examples/sdk-v2/http-python/run_prebuilt.py`.
Use a checkout containing that file. Replace its illustrative profile URL
before starting provider-backed work. It
reads `DEEPLINE_HOST_URL` and `DEEPLINE_API_KEY` from environment variables or
an uncommitted `.env.deepline` file.

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
python3 -m pip install requests
python3 docs-examples/sdk-v2/http-python/run_prebuilt.py
```

Use a workspace API key from a trusted backend environment. Do not put it in a
notebook output, client-side application, repository, or Play input.

The example saves `person-email-run.json` before polling. Keep that file with
its original workspace authorization. A rerun observes the saved run rather
than submitting another one. To start different work, use a separate working
directory after reviewing the new input.

The local wait lasts at most ten minutes, excluding individual request latency.
A timeout preserves the run file and does not cancel remote work. Completed,
failed, and cancelled outcomes are saved to `person-email-result.json`.

If the launch response is lost before its run ID is saved, the file records
an uncertain submission. The example stops rather than creating replacement
work. Investigate that submission before clearing the record.

Raw HTTP requires a server-side API key. CLI `auth status` does not export it
to the current shell. The example reads its configured environment or local
`.env.deepline`. It does not recover arbitrary global CLI credential storage.

## The caller contract

The example performs four deliberate actions:

1. `POST /api/v2/plays/run` with a saved or Prebuilt Play name and JSON input.
2. Persist `run.id` from the raw HTTP response before waiting.
3. Poll `GET /api/v2/runs/:runId` and inspect `run.status`. Terminal states are
   `completed`, `failed`, and `cancelled`.
4. Write the final response to JSON before you turn it into a CSV or update a
   destination.

If the caller restarts or its local wait expires, resume with the stored run ID.
do not create a replacement run just because local polling ended. For durable
destination writes and callbacks, use
[Production Play integration](https://deepline.com/docs/sdk-v2/production-integration.md).

## When to use each caller

| Caller | Use it when |
| - | - |
| CLI | A human or coding agent is authoring or operating a Play |
| TypeScript SDK | A TypeScript service needs Play and run handles |
| Python / raw HTTP | A non-TypeScript system invokes an already-saved or Prebuilt Play |

Use [Call Plays](https://deepline.com/docs/sdk-v2/calling-plays.md) for the CLI, TypeScript, and raw HTTP
entrypoints. Use [Runtime API reference](https://deepline.com/docs/sdk-v2/api-reference.md) for exact
request and response fields.

## Verify this task

Confirm the example source is available, authorize the intended workspace, and retain the launch response before polling.

Ask your agent to explain a failed check before repeating work or expanding the scope.


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