---
title: "Overview"
description: "How your application communicates with Output workflows over HTTP"
---

Your application talks to Output through a REST API. When you deploy Output, the API server exposes HTTP endpoints for running workflows, checking their status, and retrieving results. Your backend sends a request, Output orchestrates the workflow, and you get structured results back.

During development, the API server starts automatically on port 3001 when you run `output dev`.

## Two Ways to Run Workflows

Choose based on how long your workflow takes and how your application handles responses.

### Run and Wait (Synchronous)

`POST /workflow/run` blocks until the workflow completes and returns the result in the response body. Use this when workflows complete quickly (seconds) and your client can wait.

```bash
curl -X POST http://localhost:3001/workflow/run \
  -H "Content-Type: application/json" \
  -d '{"workflowName": "summarize_url", "input": {"url": "https://example.com/article"}}'
```

### Start and Poll (Asynchronous)

`POST /workflow/start` returns the workflow ID immediately. Poll for status and retrieve the result when ready. Use this for longer workflows — minutes or more — where blocking a request isn't practical.

```bash
# Start the workflow
curl -X POST http://localhost:3001/workflow/start \
  -H "Content-Type: application/json" \
  -d '{"workflowName": "company_research", "input": {"domain": "example.com"}}'

# Check status
curl http://localhost:3001/workflow/<workflow-id>/status

# Get result when completed
curl http://localhost:3001/workflow/<workflow-id>/result
```

## Workflow Result Payload

`POST /workflow/run` and `GET /workflow/:id/result` return the same structured workflow result:

```json
{
  "workflowId": "lead_enrichment-a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "runId": "b5c6d7e8-9012-3456-7890-abcdef123456",
  "status": "completed",
  "input": { "companyDomain": "acme.com" },
  "output": {
    "company": "Acme Corp",
    "summary": "Enterprise software company focused on..."
  },
  "trace": { "destinations": {} },
  "attributes": [
    {
      "type": "llm:usage",
      "modelId": "anthropic/claude-3-5-sonnet",
      "total": 0.0084,
      "tokensUsed": 1200,
      "usage": [
        { "type": "input", "ppm": 3, "amount": 800, "total": 0.0024 },
        { "type": "output", "ppm": 15, "amount": 400, "total": 0.006 }
      ]
    }
  ],
  "aggregations": {
    "cost": { "total": 0.0084 },
    "tokens": { "total": 1200, "input": 800, "output": 400 },
    "httpRequests": { "total": 0 }
  },
  "error": null
}
```

| Field | Description |
|-------|-------------|
| `workflowId` | Workflow execution ID. |
| `runId` | Specific Temporal run ID. |
| `status` | Current or final execution status. |
| `input` | Original workflow input. |
| `output` | Value returned by the workflow on success, or `null` on failure. |
| `trace` | Trace metadata for the run, or `null` when unavailable. |
| `attributes` | Durable workflow attributes collected during execution, such as LLM usage and HTTP cost/count attributes. |
| `aggregations` | Convenience totals derived from `attributes`, including `cost.total`, `tokens.total`, and `httpRequests.total`. |
| `error` | Error message on failure, otherwise `null`. |

`attributes` are the primary data source for usage and cost details. Use `aggregations` when you only need high-level totals for billing, reporting, or dashboards.

When a workflow fails after collecting attributes, the result still includes the available `trace`, `attributes`, and `aggregations` fields alongside the error message.

## Interacting with Running Workflows

Output supports sending data to running workflows and reading their state via signals, queries, and updates. The workflow must define handlers for these — see [External Integration](/workflows/external-integration) for how to set them up.

| Method | What it does | Use case |
|--------|-------------|----------|
| **Signal** `POST /workflow/:id/signal/:name` | Push data into a workflow | Human approval, external events |
| **Query** `POST /workflow/:id/query/:name` | Read workflow state without changing it | Progress checks, status dashboards |
| **Update** `POST /workflow/:id/update/:name` | Change state and get confirmation | Configuration changes, priority updates |

## Stopping Workflows

- `PATCH /workflow/:id/stop` — Graceful stop. Allows cleanup handlers to run.
- `POST /workflow/:id/terminate` — Force terminate. Immediate, no cleanup.

## Workflow Discovery

`GET /workflow/catalog` returns all available workflows with their input and output schemas. Use this to build dynamic UIs or validate inputs before submitting.

## Debugging

`GET /workflow/:id/trace-log` returns the full execution trace for a completed workflow. See [Tracing](/operations/tracing) for the trace format.

<Note>
For remote traces, the API server needs AWS credentials (`OUTPUT_AWS_ACCESS_KEY_ID`, `OUTPUT_AWS_SECRET_ACCESS_KEY`, `OUTPUT_AWS_REGION`).
</Note>

## What's Next

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/api/configuration">
    **Configuration.** Base URL, ports, and environment variables for the API server.
  </Card>
  <Card title="Authentication" icon="lock" href="/api/authentication">
    **Authentication.** How auth works in development vs production.
  </Card>
  <Card title="Error Responses" icon="circle-exclamation" href="/api/errors">
    **Error Responses.** Error codes, response format, and how to handle failures.
  </Card>
</CardGroup>
