Skip to main content
Human guide: work with your agent →
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 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.
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.

​
When to use each caller

Use Call Plays for the CLI, TypeScript, and raw HTTP entrypoints. Use Runtime API reference 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.