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.110
API contract2026-06-dataset-column-cell-stale-hard-cutover
Latest supported SDK0.1.110
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/"
    }
  }'
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/",
        },
    },
    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/org-createorg createSDK-facing route.src/app/api/v2/auth/cli/org-create/route.ts
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 set
org switch
SDK-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
GET/api/v2/billing/catalog/currentbilling.plans
getBillingPlans
billing plans
SDK-facing route.src/app/api/v2/billing/catalog/current/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/invoicesbilling.invoices.list
listBillingInvoices
billing invoices
SDK-facing route.src/app/api/v2/billing/invoices/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
POST/api/v2/billing/subscription/cancelbilling.subscription.cancel
cancelBillingSubscription
billing subscription cancel
SDK-facing route.src/app/api/v2/billing/subscription/cancel/route.ts
POST/api/v2/billing/subscription/checkoutbilling subscribeSDK-facing route.src/app/api/v2/billing/subscription/checkout/route.ts
GET/api/v2/billing/subscription/statusbilling.subscription.status
getBillingSubscriptionStatus
billing subscription status
SDK-facing route.src/app/api/v2/billing/subscription/status/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
POST/api/v2/cli/send-sessionsessions sendSDK-facing route.src/app/api/v2/cli/send-session/route.ts
POST/api/v2/cli/send-session/chunksessions sendSDK-facing route.src/app/api/v2/cli/send-session/chunk/route.ts
POST/api/v2/cli/send-session/finalizesessions sendSDK-facing route.src/app/api/v2/cli/send-session/finalize/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

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-sdk-enrich-inline-child-email-fallbackFixes SDK CLI deepline enrich generated play source so inline prebuilt child plays such as person-linkedin-to-email execute through the V2 child-run path without treating internal parentRunId/rootRunId metadata as public play input, an…
2026-06-billing-run-provider-audit-fieldsAdds customer-safe run-level billing auditability to existing billing usage and ledger surfaces: GET /api/v2/billing/usage recent activity and GET /api/v2/billing/ledger entries/CSV now include additive Deepline-priced provider/action/ru…
2026-06-play-run-runtime-sheet-readiness-moduleMoves POST /api/v2/plays/run pre-start Runtime Sheet data-plane readiness from the legacy customer-db provisioning facade to the deeper runtime-sheet readiness module. This is an internal server-side readiness/repair implementation chang…
2026-06-sdk-enrich-run-if-condition-statsFixes SDK CLI deepline enrich generated play source so direct --with and waterfall child run_if_js predicates are emitted as native dataset-column runIf gates, which makes V2 run summaries report skipped:condition while preserving…
2026-06-sdk-enrich-in-place-export-safetyHardens SDK CLI deepline enrich CSV export so --in-place --all overlays run output onto the original source CSV, refuses partial in-place writes that would shrink the local file, and keeps provider/failure result envelopes compact in…
2026-06-play-run-query-access-sql-metadataAdds optional sqlTableName and sqlQualifiedTableName metadata to play-run dataset packages and deepline_db_query follow-up actions so SDK/CLI/API consumers can display the exact server-returned customer storage table without deriving nam…
2026-06-deepline-plays-recipe-skill-surfaceConsolidates Deepline plays agent docs into the v1 well-known skill bundle by publishing /deepline-plays as a recipe-wrapper skill, removing legacy deepline-plays-feedback/deepline-plays-quickstart cleanup targets, and updating SDK skill…
2026-06-sdk-update-agent-skills-refreshRefreshes Deepline agent skills after a successful explicit SDK CLI deepline update for npm-global and Python-managed sidecar installs, using the existing skills-sync path and preserving dry-run/source/failure behavior. This is local C…

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. "dropleads_search_people").
providerstringYesProvider that backs this tool (e.g. "hunter", "dropleads", "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.
playReferenceprebuilt/${string}NoExplicit globally runnable play reference for play-backed catalog entries.
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 plays 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.
descriptionstringNoHuman-readable one-line description for the revision created by file-backed runs.
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 and runtime probes can pass a different profile 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 plays 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.
playNamestring | nullNoSaved play name for this run, when available.
runIdstringYesBackend run attempt id, when exposed.
parentRunIdstring | nullNoParent play-run id when this run was launched through ctx.runPlay.
rootRunIdstring | nullNoRoot play-run id for nested ctx.runPlay descendants.
typestringYesWorkflow type (typically 'Workflow').
statusstringYesHuman-readable status (e.g. 'Completed', 'Failed').
startTimestring | nullNoISO 8601 timestamp when the run started.
startedAtnumber | string | nullNoUnix epoch milliseconds when the run started, returned by normalized V2 run summaries.
closeTimestring | nullNoISO 8601 timestamp when the run finished.
finishedAtnumber | string | nullNoUnix epoch milliseconds when the run finished, returned by normalized V2 run summaries.
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.
stopAll(options?: { reason?: string }) => Promise<StopAllPlayRunsResult>YesStop active runs across the current workspace.

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.