Skip to main content
A Run represents a single agent execution. You provide instructions and optionally tools, and the agent works to complete the task.

​
What is a Run?

When you call client.run(), Subconscious creates a Run that:
  1. Receives your instructions and tools
  2. Processes the request through our inference engine
  3. Executes tool calls as needed
  4. Returns structured results

​
Run Lifecycle

Every Run progresses through a series of states:
StatusDescription
queuedRun is waiting to be processed
runningRun is actively being executed
succeededRun completed successfully
failedRun encountered an error
canceledRun was canceled by the user
timed_outRun exceeded the timeout limit

​
Creating a Run

​
Synchronous (Wait for Completion)

The simplest approach—wait for the run to complete: 
from subconscious import Subconscious

client = Subconscious(api_key="your-api-key")

run = client.run(
    engine="tim-gpt",
    input={
        "instructions": "Summarize the latest AI news",
        "tools": [{"type": "platform", "id": "web_search"}],
    },
    options={"await_completion": True},
)

print(run.result.answer)

​
Asynchronous (Fire and Forget)

Some workloads are better suited for async execution:
  • Long-running tasks — Many tool calls, large searches, multi-step plans
  • Durability requirements — You care that they finish, not that you watch every token
  • Fan-out to other systems — Pipelines, CRMs, warehouses
Start a run without waiting, then check status later: 
from subconscious import Subconscious

client = Subconscious(api_key="your-api-key")

# Start without waiting
run = client.run(
    engine="tim-gpt",
    input={"instructions": "Generate a report"},
)

print(f"Run started: {run.run_id}")

# Check status later
status = client.get(run.run_id)
print(status.status)  # 'queued' | 'running' | 'succeeded' | 'failed'

​
Polling with client.wait()

For convenience, use client.wait() to automatically poll until the run completes: 
from subconscious import Subconscious

client = Subconscious(api_key="your-api-key")

# Start a run
run = client.run(
    engine="tim-gpt",
    input={"instructions": "Generate a detailed report"},
)

# Poll until complete
result = client.wait(
    run.run_id,
    options={
        "interval_ms": 2000,  # Poll every 2 seconds
        "max_attempts": 60,   # Give up after 60 attempts
    },
)

print(result.result.answer)

​
When to Use What

PatternBest For
Sync (await_completion: true)Simple tasks, quick responses
StreamingHuman watching, chat UIs
Async + PollingBackground jobs, dashboards
Async + WebhooksIntegrations, pipelines (see Webhooks)

​
Run Response Structure

When a run completes, you receive a response with these fields: 
interface RunResponse {
  runId: string;
  status:
    | "queued"
    | "running"
    | "succeeded"
    | "failed"
    | "canceled"
    | "timed_out";
  result?: {
    answer: string;
    reasoning?: Task[];
  };
  usage?: {
    inputTokens: number;
    outputTokens: number;
    durationMs: number;
  };
  error?: {
    code: string;
    message: string;
  };
}

​
Key Fields

FieldDescription
runIdUnique identifier for this run
statusCurrent state of the run
result.answerThe agent’s final answer
result.reasoningStep-by-step reasoning process (when available)
usageToken usage and timing information
errorError details if the run failed

​
Canceling a Run

You can cancel a run that’s still in progress: 
from subconscious import Subconscious

client = Subconscious(api_key="your-api-key")

# Cancel a run in progress
client.cancel(run.run_id)

Streaming

Stream responses in real-time

Webhooks

Get notified when runs complete

Response Handling

Deep dive into parsing run results

Tools

Configure tools for your runs