Skip to main content

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.
Generated from source comments and type declarations by scripts/generate-play-sdk-reference.ts. Do not edit this file manually.

Version And Coverage

FieldValue
SDK version0.1.100
API contract2026-06-dataset-column-cell-stale-hard-cutover
Latest supported SDK0.1.100
Minimum supported SDK0.1.53
Deprecated below0.1.53
Generated sourcessrc/lib/sdk/api-routes.ts
sdk/src/types.ts
sdk/src/client.ts
sdk/src/release.ts
CoverageHTTP 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 coveredProvider-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

  1. POST /api/v2/plays/run with a saved/prebuilt name and JSON input.
  2. Read workflowId from the response. Treat it as the public run id.
  3. Poll GET /api/v2/runs/:runId or stream GET /api/v2/runs/:runId/tail.
  4. Stop when status is completed, failed, or cancelled.
  5. Read final user output from result or the compact package.outputs object.
Use the CLI or TypeScript SDK for local file compilation and artifact upload. Raw HTTP is best for backend services, Python jobs, schedulers, notebooks, and warehouses that invoke an already-saved or prebuilt play.

Tool And Provider Call Flow

  1. GET /api/v2/tools/search?q=... to discover ranked provider/tool candidates.
  2. GET /api/v2/integrations/:toolId/get to inspect input schema, pricing, extractors, and examples.
  3. POST /api/v2/integrations/:toolId/execute with payload to execute the provider-backed tool.
  4. Read normalized data from toolResponse.raw, extractedValues, and extractedLists. Do not expose provider spend; customer-visible billing is Deepline credits/USD only.
Inside a play, prefer 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.
export DEEPLINE_HOST_URL="${DEEPLINE_HOST_URL:-https://code.deepline.com}"
export DEEPLINE_API_KEY="dl_workspace_key"
Every request uses bearer auth:
Authorization: Bearer <DEEPLINE_API_KEY>

Start A Named Or Prebuilt Play

curl -X POST "$DEEPLINE_HOST_URL/api/v2/plays/run" \
  -H "Authorization: Bearer $DEEPLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prebuilt/person-linkedin-to-email",
    "input": {
      "linkedin_url": "https://www.linkedin.com/in/example-person/",
      "first_name": "Jane",
      "last_name": "Smith",
      "company_name": "ExampleCo",
      "domain": "example.com"
    }
  }'
Response:
{
  "workflowId": "play_run_...",
  "apiVersion": 2,
  "status": "running",
  "dashboardUrl": "https://code.deepline.com/dashboard/plays/..."
}

Poll Status

curl "$DEEPLINE_HOST_URL/api/v2/runs/$WORKFLOW_ID?full=true" \
  -H "Authorization: Bearer $DEEPLINE_API_KEY"
Terminal statuses are completed, failed, and cancelled. queued, running, and waiting are non-terminal.

Stream Events

curl -N "$DEEPLINE_HOST_URL/api/v2/runs/$WORKFLOW_ID/tail?mode=cli" \
  -H "Authorization: Bearer $DEEPLINE_API_KEY" \
  -H "Accept: text/event-stream"
The stream emits a canonical run snapshot first, then incremental play events until the connection closes or the run reaches terminal state.

Stop A Run

curl -X POST "$DEEPLINE_HOST_URL/api/v2/runs/$WORKFLOW_ID/stop" \
  -H "Authorization: Bearer $DEEPLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"caller cancelled"}'

Python Caller

This example is copied from docs-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
import os
import time
import json
import requests


def load_deepline_env(path=".env.deepline"):
    values = {}
    if not os.path.exists(path):
        return values
    with open(path) as env_file:
        for line in env_file:
            stripped = line.strip()
            if not stripped or stripped.startswith("#") or "=" not in stripped:
                continue
            key, value = stripped.split("=", 1)
            values[key.strip()] = value.strip().strip('"').strip("'")
    return values


deepline_env = load_deepline_env()
BASE_URL = os.environ.get(
    "DEEPLINE_HOST_URL",
    deepline_env.get("DEEPLINE_HOST_URL", "https://code.deepline.com"),
)
API_KEY = os.environ.get("DEEPLINE_API_KEY", deepline_env.get("DEEPLINE_API_KEY"))
if not API_KEY:
    raise RuntimeError("Missing DEEPLINE_API_KEY in .env.deepline")

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

start = requests.post(
    f"{BASE_URL}/api/v2/plays/run",
    headers=headers,
    json={
        "name": "prebuilt/person-linkedin-to-email",
        "input": {
            "linkedin_url": "https://www.linkedin.com/in/example-person/",
            "first_name": "Jane",
            "last_name": "Smith",
            "company_name": "ExampleCo",
            "domain": "example.com",
        },
    },
    timeout=30,
)
start.raise_for_status()
workflow_id = start.json()["workflowId"]

while True:
    status = requests.get(
        f"{BASE_URL}/api/v2/runs/{workflow_id}",
        headers=headers,
        timeout=30,
    )
    status.raise_for_status()
    body = status.json()
    if body.get("status") in {"completed", "failed", "cancelled"}:
        with open("person-email-result.json", "w") as f:
            json.dump(body, f, indent=2)
        print(body)
        break
    time.sleep(2)

Generated Route Tables

Runtime Health

MethodPathSDK/client surfacePurposeSource
GET/api/v2/healthhealthCheck API availability and SDK target health.src/app/api/v2/health/route.ts

Tool And Provider Calls

MethodPathSDK/client surfacePurposeSource
GET/api/v2/integrations/:toolIdgetToolDescribe one provider-backed tool by integration id.src/app/api/v2/integrations/[toolId]/route.ts
POST/api/v2/integrations/:toolId/executeexecuteTool
executeToolRaw
Execute one provider-backed tool call through Deepline.src/app/api/v2/integrations/execute/route.ts
GET/api/v2/integrations/:toolId/getgetToolDescribe one provider-backed tool, including schema, pricing, guidance, and extractors.src/app/api/v2/integrations/get/route.ts
GET/api/v2/integrations/listsearchToolsCompatibility discovery route for integration/tool listing.src/app/api/v2/integrations/list/route.ts
GET/api/v2/toolslistToolsList callable provider/tool definitions.src/app/api/v2/tools/route.ts
GET/api/v2/tools/searchsearchToolsSearch callable provider/tool definitions with ranked metadata search.src/app/api/v2/tools/search/route.ts

Customer Data

MethodPathSDK/client surfacePurposeSource
POST/api/v2/db/queryqueryCustomerDbRun a bounded query against the customer data plane.src/app/api/v2/db/query/route.ts

Play Runs

MethodPathSDK/client surfacePurposeSource
GET/api/v2/plays/:name/runslistPlayRunsList recent runs for one play.src/app/api/v2/plays/[name]/runs/route.ts
GET/api/v2/plays/:name/sheetruns.exportDatasetRows
getPlaySheetRows
Read/export runtime sheet rows for a run dataset.src/app/api/v2/plays/[name]/sheet/route.ts
POST/api/v2/plays/runstartPlayRun
startPlayRunFromBundle
runPlay
Start a saved, prebuilt, or artifact-backed play run.src/app/api/v2/plays/run/route.ts
GET/api/v2/runsruns.list
listRuns
List runs with filters such as play name and status.src/app/api/v2/runs/route.ts
GET/api/v2/runs/:runIdruns.get
getRunStatus
getPlayStatus
Read canonical status, result, outputs, and run package.src/app/api/v2/runs/[runId]/route.ts
GET/api/v2/runs/:runId/logsruns.logs
getRunLogs
SDK-facing route.src/app/api/v2/runs/[runId]/logs/route.ts
POST/api/v2/runs/:runId/observe-grantruns.tail
tailRun
runPlay
SDK-facing route.src/app/api/v2/runs/[runId]/observe-grant/route.ts
POST/api/v2/runs/:runId/stopruns.stop
stopRun
cancelPlay
stopPlay
Stop a running or waiting play run.src/app/api/v2/runs/[runId]/stop/route.ts
GET/api/v2/runs/:runId/tailruns.tail
tailRun
Stream canonical run events over SSE.src/app/api/v2/runs/[runId]/tail/route.ts

Play Definitions

MethodPathSDK/client surfacePurposeSource
GET/api/v2/playslistPlays
searchPlays
List or search callable plays.src/app/api/v2/plays/route.ts
DELETE/api/v2/plays/:namedeletePlayDelete a saved org-owned play.src/app/api/v2/plays/[name]/route.ts
GET/api/v2/plays/:namegetPlay
describePlay
Describe a saved, shared, or prebuilt play.src/app/api/v2/plays/[name]/route.ts
POST/api/v2/plays/:name/history/clearclearPlayHistorySDK-facing route.src/app/api/v2/plays/[name]/history/clear/route.ts
POST/api/v2/plays/:name/livepublishPlayVersionPromote a revision as the live named play.src/app/api/v2/plays/[name]/live/route.ts
GET/api/v2/plays/:name/versionslistPlayVersionsList saved play revisions.src/app/api/v2/plays/[name]/versions/route.ts

Play Artifacts

MethodPathSDK/client surfacePurposeSource
POST/api/v2/enrich/compilecompileEnrichPlanCompile legacy enrich command input into a runtime plan.src/app/api/v2/enrich/compile/route.ts
POST/api/v2/plays/artifactsregisterPlayArtifactRegister a bundled play artifact for ad hoc runs.src/app/api/v2/plays/artifacts/route.ts
POST/api/v2/plays/checkcheckPlayArtifactValidate a play bundle before storing or running it.src/app/api/v2/plays/check/route.ts
POST/api/v2/plays/files/stagestagePlayFiles
resolveStagedPlayFiles
Stage CSV or packaged files used by play runs.src/app/api/v2/plays/files/stage/route.ts

Management And CLI

MethodPathSDK/client surfacePurposeSource
POST/api/v2/auth/cli/organizationsorg listSDK-facing route.src/app/api/v2/auth/cli/organizations/route.ts
POST/api/v2/auth/cli/registerauth registerSDK-facing route.src/app/api/v2/auth/cli/register/route.ts
POST/api/v2/auth/cli/statusauth statusSDK-facing route.src/app/api/v2/auth/cli/status/route.ts
POST/api/v2/auth/cli/switchorg switchSDK-facing route.src/app/api/v2/auth/cli/switch/route.ts
GET/api/v2/billing/balancebilling balanceSDK-facing route.src/app/api/v2/billing/balance/route.ts
POST/api/v2/billing/checkoutbilling checkoutSDK-facing route.src/app/api/v2/billing/checkout/route.ts
POST/api/v2/billing/checkout/verifybilling redeemSDK-facing route.src/app/api/v2/billing/checkout/verify/route.ts
GET/api/v2/billing/ledgerbilling historySDK-facing route.src/app/api/v2/billing/ledger/route.ts
DELETE/api/v2/billing/limitbilling limit offSDK-facing route.src/app/api/v2/billing/limit/route.ts
GET/api/v2/billing/limitbilling limitSDK-facing route.src/app/api/v2/billing/limit/route.ts
POST/api/v2/billing/limitbilling limit setSDK-facing route.src/app/api/v2/billing/limit/route.ts
GET/api/v2/billing/usagebilling usageSDK-facing route.src/app/api/v2/billing/usage/route.ts
POST/api/v2/cli/feedbackfeedbackSDK-facing route.src/app/api/v2/cli/feedback/route.ts
DELETE/api/v2/plays/:name/shareunpublishSharePageSDK-facing route.src/app/api/v2/plays/[name]/share/route.ts
GET/api/v2/plays/:name/sharegetSharePageSDK-facing route.src/app/api/v2/plays/[name]/share/route.ts
PATCH/api/v2/plays/:name/shareupdateSharePageSDK-facing route.src/app/api/v2/plays/[name]/share/route.ts
POST/api/v2/plays/:name/sharepublishSharePageSDK-facing route.src/app/api/v2/plays/[name]/share/route.ts
POST/api/v2/plays/:name/share/regenerateregenerateSharePageSDK-facing route.src/app/api/v2/plays/[name]/share/regenerate/route.ts
GET/api/v2/sdk/compatcompat checkSDK-facing route.src/app/api/v2/sdk/compat/route.ts
GET/api/v2/secretssecrets list
secrets check
listSecrets
SDK-facing route.src/app/api/v2/secrets/route.ts
POST/api/v2/secretssecrets setSDK-facing route.src/app/api/v2/secrets/route.ts
DELETE/api/v2/secrets/:idsecrets deleteSDK-facing route.src/app/api/v2/secrets/[id]/route.ts
POST/api/v2/secrets/:id/testsecrets testSDK-facing route.src/app/api/v2/secrets/[id]/test/route.ts
GET/api/v2/workflowslistWorkflowsSDK-facing route.src/app/api/v2/workflows/route.ts
DELETE/api/v2/workflows/:iddeleteWorkflowSDK-facing route.src/app/api/v2/workflows/[id]/route.ts
GET/api/v2/workflows/:idgetWorkflowSDK-facing route.src/app/api/v2/workflows/[id]/route.ts
POST/api/v2/workflows/:id/disabledisableWorkflowSDK-facing route.src/app/api/v2/workflows/[id]/disable/route.ts
POST/api/v2/workflows/:id/enableenableWorkflowSDK-facing route.src/app/api/v2/workflows/[id]/enable/route.ts
GET/api/v2/workflows/:id/runslistWorkflowRunsSDK-facing route.src/app/api/v2/workflows/[id]/runs/route.ts
GET/api/v2/workflows/:id/runs/:runIdgetWorkflowRunSDK-facing route.src/app/api/v2/workflows/[id]/runs/[runId]/route.ts
POST/api/v2/workflows/:id/runs/:runId/cancelcancelWorkflowRunSDK-facing route.src/app/api/v2/workflows/[id]/runs/[runId]/cancel/route.ts
POST/api/v2/workflows/applyapplyWorkflowSDK-facing route.src/app/api/v2/workflows/apply/route.ts
POST/api/v2/workflows/callcallWorkflowSDK-facing route.src/app/api/v2/workflows/call/route.ts
POST/api/v2/workflows/lintlintWorkflowSDK-facing route.src/app/api/v2/workflows/lint/route.ts
GET/api/v2/workflows/schemagetWorkflowSchemaSDK-facing route.src/app/api/v2/workflows/schema/route.ts

Runtime Route Coverage

SectionRoutes
Runtime Health1
Tool And Provider Calls6
Customer Data1
Play Runs9
Play Definitions6
Play Artifacts4
Management And CLI35

Recent Compatible API Changes

These entries come from COMPATIBLE_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.
ChangeReason
2026-06-cli-browser-open-default-browser-detectionFixes 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-preflightAdds 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-renderRestores 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-rowsAdditive 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-reconcileFixes 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-streamAdds 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-transportAdds 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-relocationInternal 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

NameTypeRequiredDescription
toolIdstringYesUnique tool identifier used in API calls (e.g. "apollo_people_search").
providerstringYesProvider that backs this tool (e.g. "apollo", "hunter", "test").
displayNamestringYesHuman-readable name for display.
descriptionstringYesWhat this tool does — suitable for LLM tool descriptions.
categoriesDeeplineToolCategory[]YesCategorization tags (e.g. ["people", "enrichment"]).
operationstringNoOperation slug within the provider.
operationIdstringNoNormalized operation identifier.
operationAliasesstring[]NoAlternative names that resolve to this tool.
hasInputSchemabooleanNoWhether detailed input schema is available from tools describe.
hasOutputSchemabooleanNoWhether detailed output schema is available from tools describe.
inputSchemaRecord<string, unknown>NoJSON Schema describing the tool’s input parameters.
outputSchemaRecord<string, unknown>NoJSON Schema describing the tool’s output shape.
pricingToolPricingSummary | nullNoUser-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; }; }NoCopyable play-runtime guidance for V2 tool execution results.
search_scorenumberNoSearch relevance score returned by ranked tool search.
search_matchesArray<{ field: string; value: string; term?: string; }>NoSearch match snippets returned by ranked tool search.

ToolSearchOptions

Query options for ranked tool/provider discovery.

Fields

NameTypeRequiredDescription
querystringNoFree-text search query.
categoriesstringNoComma-separated category filter such as company_search or email_finder.
searchTermsstringNoOptional explicit search terms used by agent/CLI callers.
searchMode'v1' | 'v2'NoSearch algorithm/version. Defaults to the current ranked mode.
includeSearchDebugbooleanNoInclude 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

NameTypeRequiredDescription
toolsToolDefinition[]YesRanked matching tools.
countnumberNoCount included in this response when available.
totalnumberNoTotal available count when the backend reports it.
truncatedbooleanNoWhether results were truncated by server-side limits.
querystringNoEchoed query.
categoriesstring[]NoParsed category filters.
search_termsstring[]NoParsed search terms.
search_mode'v1' | 'v2'NoSearch mode used.
search_fallback_to_categorybooleanNoWhether search fell back to category matching.
omitted_plays_hintstringNoHint explaining omitted play results when searching tools only.
commandTemplates{ describe?: string; execute?: string; }NoCopyable CLI command templates for follow-up discovery/execution.
render{ sections?: Array<{ title: string; lines: string[]; }>; actions?: Array<{ label: string; command: string; }>; }NoPre-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

NameTypeRequiredDescription
statusstringYes
job_idstringNo
metaRecord<string, unknown>No
toolResponse{ raw: TData; meta?: TMeta; }Yes
extractedListsRecord<string, unknown>No
extractedValuesRecord<string, unknown>No
billingRecord<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

NameTypeRequiredDescription
namestringNoPlay name for registered revisions.
revisionIdstringNoExplicit revision ID when the caller wants a specific saved version.
artifactStorageKeystringNoR2 artifact key for ad hoc artifact-backed runs.
sourceCodestringNoSource snapshot already validated while registering this artifact.
sourceFilesRecord<string, string>NoSource graph snapshots for local helper files included in cloud preflight.
staticPipelineunknownNoStatic pipeline already produced while registering this artifact.
artifactHashstringNoArtifact content hash already validated while registering this artifact.
graphHashstringNoStatic graph hash already validated while registering this artifact.
runtimeArtifactRecord<string, unknown>NoOptional preloaded artifact snapshot for immediate ad hoc execution.
compilerManifestPlayCompilerManifestNoCompiler manifest for ad hoc graph runs, including imported play dependencies.
inputFileUploadunknownNoPrimary input file bytes for one-shot server-side staging.
packagedFileUploadsunknown[]NoPackaged file bytes for one-shot server-side staging.
inputRecord<string, unknown>NoRuntime input passed to the play function as its second argument.
inputFileunknownNoStaged file reference for the primary input file (e.g. CSV).
packagedFilesunknown[]NoAdditional staged file references (dependencies, data files).
forcebooleanNoCompatibility flag; active sibling runs are allowed.
waitForCompletionMsnumberNoOptionally let the start request wait briefly and return a terminal result.
profilestringNoPer-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

NameTypeRequiredDescription
workflowIdstringYesPublic Deepline play-run id for tracking this execution.
apiVersionnumberNoPublic Deepline play-run API version.
namestringNoPlay name (echoed back from the request).
statusstringNoInitial status (typically 'RUNNING').
runtimeBackendstringNoResolved runtime backend used for this run.
contractRecord<string, unknown> | nullNoCanonical run contract compatibility metadata.
dashboardUrlstringNoDashboard URL for the named play.
finalStatusunknownNoTerminal status returned when the start request used a short completion wait.
packagePlayRunPackageNoCanonical 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

NameTypeRequiredDescription
runIdstringYesPublic play-run identifier.
apiVersionnumberNoPublic Deepline play-run API version.
namestringNoSaved play name for this run, when available.
playNamestringNoAlias for name used by run/result APIs.
dashboardUrlstringNoDashboard URL for inspecting the play and its run output in the app.
status| 'queued' | 'running' | 'waiting' | 'completed' | 'failed' | 'cancelled'YesProduct-level play-run state.
progressPlayProgressStatusNoExecution progress with logs and error details.
resultunknownNoPartial or final result. Available once the play returns.
packagePlayRunPackageNoCompact typed run package returned by current run status endpoints.
outputsPlayRunPackage['outputs']NoCompact typed output summaries, mirrored from the run package when present.
run{ id?: string; startTime?: string | null; closeTime?: string | null; [key: string]: unknown; } | nullNoScheduler-backed run metadata when returned by the status endpoint.
resultViewunknownNoServer-rendered result view metadata for CLI/UI summaries.
contractRecord<string, unknown> | nullNoCanonical run contract snapshot metadata, when available.
wait{ kind: 'integration_event' | 'sleep'; boundaryId?: string; eventKey?: string; until?: number; } | nullNoIf the run is blocked on a durable boundary, expose the public wait state.
nextPlayRunPackage['next'] | Record<string, unknown>NoStructured 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

NameTypeRequiredDescription
schemaVersion1YesPackage schema version.
kind'play_run'YesPackage discriminator.
run{ id: string; playName: string; status: string; dashboardUrl?: string; updatedAt?: number | null; startedAt?: number | null; finishedAt?: number | null; durationMs?: number | null; error?: string; }YesRun identity, status, timing, and dashboard metadata.
stepsArray<Record<string, unknown>>YesStep-level summaries emitted by the runtime.
outputsRecord<string, Record<string, unknown>>YesNamed output summaries, including dataset handles and scalar outputs.
next{ inspect?: PlayRunActionPackage; export?: PlayRunActionPackage; query?: PlayRunActionPackage; }NoFollow-up actions a caller can perform against the run.

PlayRunListItem

Summary of a single play run, returned by DeeplineClient.listPlayRuns.

Fields

NameTypeRequiredDescription
workflowIdstringYesPublic Deepline play-run id.
runIdstringYesBackend run attempt id, when exposed.
typestringYesWorkflow type (typically 'Workflow').
statusstringYesHuman-readable status (e.g. 'Completed', 'Failed').
startTimestring | nullYesISO 8601 timestamp when the run started.
closeTimestring | nullYesISO 8601 timestamp when the run finished.
executionTimestring | nullYesDuration string (e.g. '2.5s').
billingTotalCreditsnumberNoTotal Deepline credits charged for the run, when available.
billingMaxCreditsPerRunnumber | nullNoConfigured per-run Deepline credit cap, when available.
memo{ orgId: string; playName: string; userId: string | null; }YesMetadata attached to the workflow.

StopPlayRunResult

Result returned by DeeplineClient.stopPlay.

Fields

NameTypeRequiredDescription
runIdstringYesPublic play-run identifier the stop request targeted.
stoppedbooleanYesWhether the server confirmed the run was stopped.
hitlCancelledCountnumberYesNumber of open HITL interactions marked cancelled.
staleSchedulerStatebooleanNoTrue when the scheduler state for the run was stale and the stop could
not be confirmed. Absent on older servers (treated as confirmed).
errorstringNoServer-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

NameTypeRequiredDescription
get(runId: string, options?: { full?: boolean }) => Promise<PlayStatus>YesGet current run status by public run id.
list(options: RunsListOptions) => Promise<PlayRunListItem[]>YesList runs for one play, optionally filtered by status.
tail(runId: string, options?: RunsTailOptions) => Promise<PlayStatus>YesStream run events and return the latest/terminal run status.
logs(runId: string, options?: RunsLogsOptions) => Promise<RunsLogsResult>YesFetch persisted log lines for a run.
exportDatasetRows(input: { playName: string; tableNamespace: string; runId?: string; limit?: number; offset?: number; }) => Promise<PlaySheetRowsResult>YesExport persisted rows for a runtime-sheet dataset/table namespace.
stop( runId: string, options?: { reason?: string }, ) => Promise<StopPlayRunResult>YesStop 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

NameTypeRequiredDescription
commandstringYesDatabase command executed by the query endpoint.
row_countnumber | nullYesTotal affected row count when reported by the database.
row_count_returnednumberYesNumber of rows included in this response.
truncatedbooleanYesWhether server-side row limits truncated the result.
columnsCustomerDbColumn[]YesColumn metadata for the returned rows.
rowsunknown[]YesResult rows.