Runtime API Reference
Generated from the SDK route registry and public SDK types by
scripts/generate-play-sdk-reference.ts. Do not edit this file manually.scripts/generate-play-sdk-reference.ts. Do not edit this file manually.
Version And Coverage
| Field | Value |
|---|---|
| SDK version | 0.1.100 |
| API contract | 2026-06-dataset-column-cell-stale-hard-cutover |
| Latest supported SDK | 0.1.100 |
| Minimum supported SDK | 0.1.53 |
| Deprecated below | 0.1.53 |
| Generated sources | src/lib/sdk/api-routes.tssdk/src/types.tssdk/src/client.tssdk/src/release.ts |
| Coverage | HTTP and SDK client surface for runtime calls: health, tool/provider discovery and execution, customer data queries, play runs, play definitions, play artifacts, files, and run inspection. |
| Not covered | Provider-specific schemas, dashboard-only UI routes, billing/auth setup guides, and tutorial prose. Provider-specific schemas are returned by the generated tool describe routes. |
Best Current Pattern
Strong runtime API references lead with base URL, auth, version/contract metadata, language examples, and exact generated route tables. Deepline follows that shape here: use the quick call flows first, then the generated route and type tables below for contract details.Quick Call Flow
POST /api/v2/plays/runwith a saved/prebuiltnameand JSONinput.- Read
workflowIdfrom the response. Treat it as the public run id. - Poll
GET /api/v2/runs/:runIdor streamGET /api/v2/runs/:runId/tail. - Stop when
statusiscompleted,failed, orcancelled. - Read final user output from
resultor the compactpackage.outputsobject.
Tool And Provider Call Flow
GET /api/v2/tools/search?q=...to discover ranked provider/tool candidates.GET /api/v2/integrations/:toolId/getto inspect input schema, pricing, extractors, and examples.POST /api/v2/integrations/:toolId/executewithpayloadto execute the provider-backed tool.- Read normalized data from
toolResponse.raw,extractedValues, andextractedLists. Do not expose provider spend; customer-visible billing is Deepline credits/USD only.
ctx.tools.execute(...) so calls are durable, idempotent, and recorded in run progress. From a regular SDK process, use Deepline.connect().tools.execute(...) or client.executeTool(...).
Authentication
Use the Deepline host plus a workspace API key from a trusted backend environment.Start A Named Or Prebuilt Play
Poll Status
completed, failed, and cancelled. queued, running, and waiting are non-terminal.
Stream Events
Stop A Run
Python Caller
This example is copied fromdocs-examples/sdk-v2/http-python/run_prebuilt.py and compiled by bun run docs:sdk-v2:check.
Source: docs-examples/sdk-v2/http-python/run_prebuilt.py
Generated Route Tables
Runtime Health
| Method | Path | SDK/client surface | Purpose | Source |
|---|---|---|---|---|
GET | /api/v2/health | health | Check API availability and SDK target health. | src/app/api/v2/health/route.ts |
Tool And Provider Calls
| Method | Path | SDK/client surface | Purpose | Source |
|---|---|---|---|---|
GET | /api/v2/integrations/:toolId | getTool | Describe one provider-backed tool by integration id. | src/app/api/v2/integrations/[toolId]/route.ts |
POST | /api/v2/integrations/:toolId/execute | executeToolexecuteToolRaw | Execute one provider-backed tool call through Deepline. | src/app/api/v2/integrations/execute/route.ts |
GET | /api/v2/integrations/:toolId/get | getTool | Describe one provider-backed tool, including schema, pricing, guidance, and extractors. | src/app/api/v2/integrations/get/route.ts |
GET | /api/v2/integrations/list | searchTools | Compatibility discovery route for integration/tool listing. | src/app/api/v2/integrations/list/route.ts |
GET | /api/v2/tools | listTools | List callable provider/tool definitions. | src/app/api/v2/tools/route.ts |
GET | /api/v2/tools/search | searchTools | Search callable provider/tool definitions with ranked metadata search. | src/app/api/v2/tools/search/route.ts |
Customer Data
| Method | Path | SDK/client surface | Purpose | Source |
|---|---|---|---|---|
POST | /api/v2/db/query | queryCustomerDb | Run a bounded query against the customer data plane. | src/app/api/v2/db/query/route.ts |
Play Runs
| Method | Path | SDK/client surface | Purpose | Source |
|---|---|---|---|---|
GET | /api/v2/plays/:name/runs | listPlayRuns | List recent runs for one play. | src/app/api/v2/plays/[name]/runs/route.ts |
GET | /api/v2/plays/:name/sheet | runs.exportDatasetRowsgetPlaySheetRows | Read/export runtime sheet rows for a run dataset. | src/app/api/v2/plays/[name]/sheet/route.ts |
POST | /api/v2/plays/run | startPlayRunstartPlayRunFromBundlerunPlay | Start a saved, prebuilt, or artifact-backed play run. | src/app/api/v2/plays/run/route.ts |
GET | /api/v2/runs | runs.listlistRuns | List runs with filters such as play name and status. | src/app/api/v2/runs/route.ts |
GET | /api/v2/runs/:runId | runs.getgetRunStatusgetPlayStatus | Read canonical status, result, outputs, and run package. | src/app/api/v2/runs/[runId]/route.ts |
GET | /api/v2/runs/:runId/logs | runs.logsgetRunLogs | SDK-facing route. | src/app/api/v2/runs/[runId]/logs/route.ts |
POST | /api/v2/runs/:runId/observe-grant | runs.tailtailRunrunPlay | SDK-facing route. | src/app/api/v2/runs/[runId]/observe-grant/route.ts |
POST | /api/v2/runs/:runId/stop | runs.stopstopRuncancelPlaystopPlay | Stop a running or waiting play run. | src/app/api/v2/runs/[runId]/stop/route.ts |
GET | /api/v2/runs/:runId/tail | runs.tailtailRun | Stream canonical run events over SSE. | src/app/api/v2/runs/[runId]/tail/route.ts |
Play Definitions
| Method | Path | SDK/client surface | Purpose | Source |
|---|---|---|---|---|
GET | /api/v2/plays | listPlayssearchPlays | List or search callable plays. | src/app/api/v2/plays/route.ts |
DELETE | /api/v2/plays/:name | deletePlay | Delete a saved org-owned play. | src/app/api/v2/plays/[name]/route.ts |
GET | /api/v2/plays/:name | getPlaydescribePlay | Describe a saved, shared, or prebuilt play. | src/app/api/v2/plays/[name]/route.ts |
POST | /api/v2/plays/:name/history/clear | clearPlayHistory | SDK-facing route. | src/app/api/v2/plays/[name]/history/clear/route.ts |
POST | /api/v2/plays/:name/live | publishPlayVersion | Promote a revision as the live named play. | src/app/api/v2/plays/[name]/live/route.ts |
GET | /api/v2/plays/:name/versions | listPlayVersions | List saved play revisions. | src/app/api/v2/plays/[name]/versions/route.ts |
Play Artifacts
| Method | Path | SDK/client surface | Purpose | Source |
|---|---|---|---|---|
POST | /api/v2/enrich/compile | compileEnrichPlan | Compile legacy enrich command input into a runtime plan. | src/app/api/v2/enrich/compile/route.ts |
POST | /api/v2/plays/artifacts | registerPlayArtifact | Register a bundled play artifact for ad hoc runs. | src/app/api/v2/plays/artifacts/route.ts |
POST | /api/v2/plays/check | checkPlayArtifact | Validate a play bundle before storing or running it. | src/app/api/v2/plays/check/route.ts |
POST | /api/v2/plays/files/stage | stagePlayFilesresolveStagedPlayFiles | Stage CSV or packaged files used by play runs. | src/app/api/v2/plays/files/stage/route.ts |
Management And CLI
| Method | Path | SDK/client surface | Purpose | Source |
|---|---|---|---|---|
POST | /api/v2/auth/cli/organizations | org list | SDK-facing route. | src/app/api/v2/auth/cli/organizations/route.ts |
POST | /api/v2/auth/cli/register | auth register | SDK-facing route. | src/app/api/v2/auth/cli/register/route.ts |
POST | /api/v2/auth/cli/status | auth status | SDK-facing route. | src/app/api/v2/auth/cli/status/route.ts |
POST | /api/v2/auth/cli/switch | org switch | SDK-facing route. | src/app/api/v2/auth/cli/switch/route.ts |
GET | /api/v2/billing/balance | billing balance | SDK-facing route. | src/app/api/v2/billing/balance/route.ts |
POST | /api/v2/billing/checkout | billing checkout | SDK-facing route. | src/app/api/v2/billing/checkout/route.ts |
POST | /api/v2/billing/checkout/verify | billing redeem | SDK-facing route. | src/app/api/v2/billing/checkout/verify/route.ts |
GET | /api/v2/billing/ledger | billing history | SDK-facing route. | src/app/api/v2/billing/ledger/route.ts |
DELETE | /api/v2/billing/limit | billing limit off | SDK-facing route. | src/app/api/v2/billing/limit/route.ts |
GET | /api/v2/billing/limit | billing limit | SDK-facing route. | src/app/api/v2/billing/limit/route.ts |
POST | /api/v2/billing/limit | billing limit set | SDK-facing route. | src/app/api/v2/billing/limit/route.ts |
GET | /api/v2/billing/usage | billing usage | SDK-facing route. | src/app/api/v2/billing/usage/route.ts |
POST | /api/v2/cli/feedback | feedback | SDK-facing route. | src/app/api/v2/cli/feedback/route.ts |
DELETE | /api/v2/plays/:name/share | unpublishSharePage | SDK-facing route. | src/app/api/v2/plays/[name]/share/route.ts |
GET | /api/v2/plays/:name/share | getSharePage | SDK-facing route. | src/app/api/v2/plays/[name]/share/route.ts |
PATCH | /api/v2/plays/:name/share | updateSharePage | SDK-facing route. | src/app/api/v2/plays/[name]/share/route.ts |
POST | /api/v2/plays/:name/share | publishSharePage | SDK-facing route. | src/app/api/v2/plays/[name]/share/route.ts |
POST | /api/v2/plays/:name/share/regenerate | regenerateSharePage | SDK-facing route. | src/app/api/v2/plays/[name]/share/regenerate/route.ts |
GET | /api/v2/sdk/compat | compat check | SDK-facing route. | src/app/api/v2/sdk/compat/route.ts |
GET | /api/v2/secrets | secrets listsecrets checklistSecrets | SDK-facing route. | src/app/api/v2/secrets/route.ts |
POST | /api/v2/secrets | secrets set | SDK-facing route. | src/app/api/v2/secrets/route.ts |
DELETE | /api/v2/secrets/:id | secrets delete | SDK-facing route. | src/app/api/v2/secrets/[id]/route.ts |
POST | /api/v2/secrets/:id/test | secrets test | SDK-facing route. | src/app/api/v2/secrets/[id]/test/route.ts |
GET | /api/v2/workflows | listWorkflows | SDK-facing route. | src/app/api/v2/workflows/route.ts |
DELETE | /api/v2/workflows/:id | deleteWorkflow | SDK-facing route. | src/app/api/v2/workflows/[id]/route.ts |
GET | /api/v2/workflows/:id | getWorkflow | SDK-facing route. | src/app/api/v2/workflows/[id]/route.ts |
POST | /api/v2/workflows/:id/disable | disableWorkflow | SDK-facing route. | src/app/api/v2/workflows/[id]/disable/route.ts |
POST | /api/v2/workflows/:id/enable | enableWorkflow | SDK-facing route. | src/app/api/v2/workflows/[id]/enable/route.ts |
GET | /api/v2/workflows/:id/runs | listWorkflowRuns | SDK-facing route. | src/app/api/v2/workflows/[id]/runs/route.ts |
GET | /api/v2/workflows/:id/runs/:runId | getWorkflowRun | SDK-facing route. | src/app/api/v2/workflows/[id]/runs/[runId]/route.ts |
POST | /api/v2/workflows/:id/runs/:runId/cancel | cancelWorkflowRun | SDK-facing route. | src/app/api/v2/workflows/[id]/runs/[runId]/cancel/route.ts |
POST | /api/v2/workflows/apply | applyWorkflow | SDK-facing route. | src/app/api/v2/workflows/apply/route.ts |
POST | /api/v2/workflows/call | callWorkflow | SDK-facing route. | src/app/api/v2/workflows/call/route.ts |
POST | /api/v2/workflows/lint | lintWorkflow | SDK-facing route. | src/app/api/v2/workflows/lint/route.ts |
GET | /api/v2/workflows/schema | getWorkflowSchema | SDK-facing route. | src/app/api/v2/workflows/schema/route.ts |
Runtime Route Coverage
| Section | Routes |
|---|---|
| Runtime Health | 1 |
| Tool And Provider Calls | 6 |
| Customer Data | 1 |
| Play Runs | 9 |
| Play Definitions | 6 |
| Play Artifacts | 4 |
| Management And CLI | 35 |
Recent Compatible API Changes
These entries come fromCOMPATIBLE_SDK_API_CHANGES and explain additive changes that did not require an SDK API-contract bump. The full ledger lives in src/lib/sdk/api-routes.ts.
| Change | Reason |
|---|---|
2026-06-cli-browser-open-default-browser-detection | Fixes the SDK CLI browser opener (sdk/src/cli/utils.ts) so deepline plays run reuses and focuses an existing browser tab instead of spawning dozens of duplicates. Default-browser detection now parses the macOS LaunchServices plist stru… |
2026-06-run-start-contract-preflight | Adds a submit-time preflight to POST /api/v2/plays/run: when a request carries a client-bundled runtimeArtifact, the route compares the CLI’s x-deepline-api-contract header against this runtime’s contract and returns HTTP 426 with a clea… |
2026-06-cli-play-watch-step-progress-render | Restores live per-step lines in human deepline plays run --watch (SDK 0.1.93 regression): the CLI now prints step <name>: running|completed transitions from the existing play.step.status events the shared snapshot differ already emit… |
2026-06-cli-failed-run-recoverable-rows | Additive CLI text-render change for failed runs: deepline plays run --watch and run summaries now print “recoverable: N rows persisted” plus the runs export command when a failed run has persisted runtime-sheet rows, sourced from add… |
2026-06-cli-play-watch-durable-summary-reconcile | Fixes a render race in deepline plays run --watch: when the streamed terminal status arrives with an empty step ledger for a fast run, resolvePlayRunOutputStatus now re-fetches the durable run package (GET /api/v2/runs/:id, already use… |
2026-06-run-log-stream | Adds GET /api/v2/runs/:runId/logs — paginated full-retention Run Log Stream reads with absolute per-run sequence numbers (ADR-0009). client.runs.logs and deepline runs logs move from slicing the snapshot tail to this route and now pagi… |
2026-06-run-observe-grant-transport | Adds POST /api/v2/runs/:runId/observe-grant plus a Convex Run Snapshot subscription transport for run watching (ADR-0008). New SDK/CLI versions try the subscription transport first and fall back to the existing GET /api/v2/runs/:runId/ta… |
2026-06-sdk-plays-internal-module-relocation | Internal module relocation only for POST /api/v2/plays/run and POST /api/v2/plays/artifacts: resolveStaticPipelineTree now imports from @shared_libs/plays/resolve-static-pipeline (static-pipeline/compiler-manifest consolidation), schedul… |
Public Types
ToolDefinition
Summary definition of a callable provider-backed tool.
Returned by DeeplineClient.listTools and ranked tool search. Use
getTool(toolId) or the matching HTTP describe route for provider-specific
schema, examples, pricing, and extraction guidance before executing.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
toolId | string | Yes | Unique tool identifier used in API calls (e.g. "apollo_people_search"). |
provider | string | Yes | Provider that backs this tool (e.g. "apollo", "hunter", "test"). |
displayName | string | Yes | Human-readable name for display. |
description | string | Yes | What this tool does — suitable for LLM tool descriptions. |
categories | DeeplineToolCategory[] | Yes | Categorization tags (e.g. ["people", "enrichment"]). |
operation | string | No | Operation slug within the provider. |
operationId | string | No | Normalized operation identifier. |
operationAliases | string[] | No | Alternative names that resolve to this tool. |
hasInputSchema | boolean | No | Whether detailed input schema is available from tools describe. |
hasOutputSchema | boolean | No | Whether detailed output schema is available from tools describe. |
inputSchema | Record<string, unknown> | No | JSON Schema describing the tool’s input parameters. |
outputSchema | Record<string, unknown> | No | JSON Schema describing the tool’s output shape. |
pricing | ToolPricingSummary | null | No | User-facing pricing summary. Internal provider/settlement costs are intentionally omitted. |
usageGuidance | { execute?: string; prefer?: string[]; access?: { extractedLists?: { expression?: string; meaning?: string; }; extractedValues?: { expression?: string; meaning?: string; }; rawToolResponse?: { expression?: string; meaning?: string; }; invalidGetterHint?: string; }; toolExecutionResult?: { type?: 'ToolExecutionResult'; toolResponse?: { raw?: string; meta?: string; }; meta?: string; extractedLists?: | Array<{ name: string; expression: string; details?: { strategy?: string; rawToolOutputPaths?: string[]; candidatePaths?: string[]; }; }> | Record< string, { expression: string; details?: { strategy?: string; rawToolOutputPaths?: string[]; candidatePaths?: string[]; }; } >; extractedValues?: | Array<{ name: string; expression: string; details?: { strategy?: string; rawToolOutputPaths?: string[]; candidatePaths?: string[]; }; }> | Record< string, { expression: string; details?: { strategy?: string; rawToolOutputPaths?: string[]; candidatePaths?: string[]; }; } >; [key: string]: unknown; }; } | No | Copyable play-runtime guidance for V2 tool execution results. |
search_score | number | No | Search relevance score returned by ranked tool search. |
search_matches | Array<{ field: string; value: string; term?: string; }> | No | Search match snippets returned by ranked tool search. |
ToolSearchOptions
Query options for ranked tool/provider discovery.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
query | string | No | Free-text search query. |
categories | string | No | Comma-separated category filter such as company_search or email_finder. |
searchTerms | string | No | Optional explicit search terms used by agent/CLI callers. |
searchMode | 'v1' | 'v2' | No | Search algorithm/version. Defaults to the current ranked mode. |
includeSearchDebug | boolean | No | Include backend debug metadata in the search response. |
ToolSearchResult
Ranked tool/provider discovery response.
Includes matching tools plus render/action hints used by the CLI and agents.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
tools | ToolDefinition[] | Yes | Ranked matching tools. |
count | number | No | Count included in this response when available. |
total | number | No | Total available count when the backend reports it. |
truncated | boolean | No | Whether results were truncated by server-side limits. |
query | string | No | Echoed query. |
categories | string[] | No | Parsed category filters. |
search_terms | string[] | No | Parsed search terms. |
search_mode | 'v1' | 'v2' | No | Search mode used. |
search_fallback_to_category | boolean | No | Whether search fell back to category matching. |
omitted_plays_hint | string | No | Hint explaining omitted play results when searching tools only. |
commandTemplates | { describe?: string; execute?: string; } | No | Copyable CLI command templates for follow-up discovery/execution. |
render | { sections?: Array<{ title: string; lines: string[]; }>; actions?: Array<{ label: string; command: string; }>; } | No | Pre-rendered sections and actions for CLI/agent display. |
ToolExecution
Standard provider/tool execution envelope returned by low-level SDK calls.
toolResponse.raw contains the provider result. extractedValues and
extractedLists contain Deepline-normalized getters when the tool exposes
them. Billing fields are Deepline-facing and must not expose provider spend.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
status | string | Yes | |
job_id | string | No | |
meta | Record<string, unknown> | No | |
toolResponse | { raw: TData; meta?: TMeta; } | Yes | |
extractedLists | Record<string, unknown> | No | |
extractedValues | Record<string, unknown> | No | |
billing | Record<string, unknown> | No |
StartPlayRunRequest
Request body for starting a play run via DeeplineClient.startPlayRun.
Internal/advanced request shape for low-level submission primitives.
Most callers should prefer deepline play run, DeeplineClient.runPlay,
or Deepline.connect.
Either name (for live plays) or artifactStorageKey (for packaged ad hoc runs) is required.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
name | string | No | Play name for registered revisions. |
revisionId | string | No | Explicit revision ID when the caller wants a specific saved version. |
artifactStorageKey | string | No | R2 artifact key for ad hoc artifact-backed runs. |
sourceCode | string | No | Source snapshot already validated while registering this artifact. |
sourceFiles | Record<string, string> | No | Source graph snapshots for local helper files included in cloud preflight. |
staticPipeline | unknown | No | Static pipeline already produced while registering this artifact. |
artifactHash | string | No | Artifact content hash already validated while registering this artifact. |
graphHash | string | No | Static graph hash already validated while registering this artifact. |
runtimeArtifact | Record<string, unknown> | No | Optional preloaded artifact snapshot for immediate ad hoc execution. |
compilerManifest | PlayCompilerManifest | No | Compiler manifest for ad hoc graph runs, including imported play dependencies. |
inputFileUpload | unknown | No | Primary input file bytes for one-shot server-side staging. |
packagedFileUploads | unknown[] | No | Packaged file bytes for one-shot server-side staging. |
input | Record<string, unknown> | No | Runtime input passed to the play function as its second argument. |
inputFile | unknown | No | Staged file reference for the primary input file (e.g. CSV). |
packagedFiles | unknown[] | No | Additional staged file references (dependencies, data files). |
force | boolean | No | Compatibility flag; active sibling runs are allowed. |
waitForCompletionMs | number | No | Optionally let the start request wait briefly and return a terminal result. |
profile | string | No | Per-run execution profile override. The server defaults to workers_edge;tests can pass local here. Most callers should leave this unset. |
PlayRunStart
Response from starting a play run.
Internal/advanced payload returned by low-level play submission primitives.
Most callers should prefer deepline play run, DeeplineClient.runPlay,
or PlayJob.get.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
workflowId | string | Yes | Public Deepline play-run id for tracking this execution. |
apiVersion | number | No | Public Deepline play-run API version. |
name | string | No | Play name (echoed back from the request). |
status | string | No | Initial status (typically 'RUNNING'). |
runtimeBackend | string | No | Resolved runtime backend used for this run. |
contract | Record<string, unknown> | null | No | Canonical run contract compatibility metadata. |
dashboardUrl | string | No | Dashboard URL for the named play. |
finalStatus | unknown | No | Terminal status returned when the start request used a short completion wait. |
package | PlayRunPackage | No | Canonical compact run package returned by current SDK/API responses. |
PlayStatus
Current status of a play execution, returned by DeeplineClient.getPlayStatus.
Poll this until status reaches a terminal state:
'completed' | 'failed' | 'cancelled'.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
runId | string | Yes | Public play-run identifier. |
apiVersion | number | No | Public Deepline play-run API version. |
name | string | No | Saved play name for this run, when available. |
playName | string | No | Alias for name used by run/result APIs. |
dashboardUrl | string | No | Dashboard URL for inspecting the play and its run output in the app. |
status | | 'queued' | 'running' | 'waiting' | 'completed' | 'failed' | 'cancelled' | Yes | Product-level play-run state. |
progress | PlayProgressStatus | No | Execution progress with logs and error details. |
result | unknown | No | Partial or final result. Available once the play returns. |
package | PlayRunPackage | No | Compact typed run package returned by current run status endpoints. |
outputs | PlayRunPackage['outputs'] | No | Compact typed output summaries, mirrored from the run package when present. |
run | { id?: string; startTime?: string | null; closeTime?: string | null; [key: string]: unknown; } | null | No | Scheduler-backed run metadata when returned by the status endpoint. |
resultView | unknown | No | Server-rendered result view metadata for CLI/UI summaries. |
contract | Record<string, unknown> | null | No | Canonical run contract snapshot metadata, when available. |
wait | { kind: 'integration_event' | 'sleep'; boundaryId?: string; eventKey?: string; until?: number; } | null | No | If the run is blocked on a durable boundary, expose the public wait state. |
next | PlayRunPackage['next'] | Record<string, unknown> | No | Structured follow-up actions for inspect/query/export. |
PlayRunPackage
Compact canonical package for an inspected play run.
This object is designed for SDK/CLI/API consumers that need stable run
metadata, output handles, and follow-up actions without reading dashboard
internals.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
schemaVersion | 1 | Yes | Package schema version. |
kind | 'play_run' | Yes | Package discriminator. |
run | { id: string; playName: string; status: string; dashboardUrl?: string; updatedAt?: number | null; startedAt?: number | null; finishedAt?: number | null; durationMs?: number | null; error?: string; } | Yes | Run identity, status, timing, and dashboard metadata. |
steps | Array<Record<string, unknown>> | Yes | Step-level summaries emitted by the runtime. |
outputs | Record<string, Record<string, unknown>> | Yes | Named output summaries, including dataset handles and scalar outputs. |
next | { inspect?: PlayRunActionPackage; export?: PlayRunActionPackage; query?: PlayRunActionPackage; } | No | Follow-up actions a caller can perform against the run. |
PlayRunListItem
Summary of a single play run, returned by DeeplineClient.listPlayRuns.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
workflowId | string | Yes | Public Deepline play-run id. |
runId | string | Yes | Backend run attempt id, when exposed. |
type | string | Yes | Workflow type (typically 'Workflow'). |
status | string | Yes | Human-readable status (e.g. 'Completed', 'Failed'). |
startTime | string | null | Yes | ISO 8601 timestamp when the run started. |
closeTime | string | null | Yes | ISO 8601 timestamp when the run finished. |
executionTime | string | null | Yes | Duration string (e.g. '2.5s'). |
billingTotalCredits | number | No | Total Deepline credits charged for the run, when available. |
billingMaxCreditsPerRun | number | null | No | Configured per-run Deepline credit cap, when available. |
memo | { orgId: string; playName: string; userId: string | null; } | Yes | Metadata attached to the workflow. |
StopPlayRunResult
Result returned by DeeplineClient.stopPlay.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
runId | string | Yes | Public play-run identifier the stop request targeted. |
stopped | boolean | Yes | Whether the server confirmed the run was stopped. |
hitlCancelledCount | number | Yes | Number of open HITL interactions marked cancelled. |
staleSchedulerState | boolean | No | True when the scheduler state for the run was stale and the stop could not be confirmed. Absent on older servers (treated as confirmed). |
error | string | No | Server-side error detail when the stop was not confirmed. |
RunsNamespace
Public runs namespace exposed as client.runs.
This namespace mirrors the canonical /api/v2/runs resource family and is
the preferred low-level surface for polling, streaming, stopping, reading
logs, and exporting durable dataset rows.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
get | (runId: string, options?: { full?: boolean }) => Promise<PlayStatus> | Yes | Get current run status by public run id. |
list | (options: RunsListOptions) => Promise<PlayRunListItem[]> | Yes | List runs for one play, optionally filtered by status. |
tail | (runId: string, options?: RunsTailOptions) => Promise<PlayStatus> | Yes | Stream run events and return the latest/terminal run status. |
logs | (runId: string, options?: RunsLogsOptions) => Promise<RunsLogsResult> | Yes | Fetch persisted log lines for a run. |
exportDatasetRows | (input: { playName: string; tableNamespace: string; runId?: string; limit?: number; offset?: number; }) => Promise<PlaySheetRowsResult> | Yes | Export persisted rows for a runtime-sheet dataset/table namespace. |
stop | ( runId: string, options?: { reason?: string }, ) => Promise<StopPlayRunResult> | Yes | Stop a running/waiting run. |
CustomerDbQueryResult
Result returned by DeeplineClient.queryCustomerDb.
Rows are intentionally untyped because the schema depends on the caller’s SQL
query and selected customer tables.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
command | string | Yes | Database command executed by the query endpoint. |
row_count | number | null | Yes | Total affected row count when reported by the database. |
row_count_returned | number | Yes | Number of rows included in this response. |
truncated | boolean | Yes | Whether server-side row limits truncated the result. |
columns | CustomerDbColumn[] | Yes | Column metadata for the returned rows. |
rows | unknown[] | Yes | Result rows. |