# Runs

## Start a technique run

`client.techniques.runs.create(stringtechniqueID, RunCreateParamsbody, RequestOptionsoptions?): RunCreateResponse`

**post** `/techniques/{techniqueId}/runs`

Starts a run for a specific technique using the backward-compatible nested route. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.

### Parameters

- `techniqueID: string`

  Technique identifier or slug

- `body: RunCreateParams`

  - `inputs: Array<Input>`

    Technique inputs

    - `id: string`

      Technique input identifier

    - `type: "text" | "imageUrl" | "videoUrl"`

      Technique input type

      - `"text"`

      - `"imageUrl"`

      - `"videoUrl"`

    - `value: string`

      Technique input value

  - `mode: "async" | "stream"`

    Technique run execution mode

    - `"async"`

    - `"stream"`

  - `callback_url?: string`

    HTTPS callback URL for asynchronous run completion notifications

  - `idempotency_key?: string`

    Idempotency key for safely retrying requests

### Returns

- `RunCreateResponse`

  - `created_at: number`

  - `progress: number`

  - `run_id: string`

    Run identifier

  - `status: "pending" | "running" | "completed" | "failed"`

    - `"pending"`

    - `"running"`

    - `"completed"`

    - `"failed"`

  - `charged_cost?: number`

    Cost charged in USD

  - `completed_at?: number`

  - `error_code?: string`

    Machine-readable run error code

  - `error_message?: string`

    Human-readable run error message

  - `outputs?: Array<Output>`

    - `output_id: string`

      Run output identifier

    - `type: "imageUrl" | "videoUrl" | "audioUrl" | 2 more`

      Run output media type

      - `"imageUrl"`

      - `"videoUrl"`

      - `"audioUrl"`

      - `"text"`

      - `"documentUrl"`

    - `url: string`

      Run output URL or text content

  - `poll_url?: string`

    URL to poll pending/running runs or fetch completed/failed run details.

  - `started_at?: number`

### Example

```typescript
import FLORA from '@flora-ai/flora';

const client = new FLORA({
  apiKey: process.env['FLORA_API_KEY'], // This is the default and can be omitted
});

const run = await client.techniques.runs.create('art-directors-critique', {
  inputs: [
    {
      id: 'id',
      type: 'text',
      value: 'value',
    },
  ],
  mode: 'async',
});

console.log(run.run_id);
```

#### Response

```json
{
  "created_at": 0,
  "progress": 0,
  "run_id": "run_abc123",
  "status": "pending",
  "charged_cost": 0,
  "completed_at": 0,
  "error_code": "provider_error",
  "error_message": "The provider failed to complete the generation.",
  "outputs": [
    {
      "output_id": "output_1",
      "type": "imageUrl",
      "url": "https://media.flora.ai/output.png"
    }
  ],
  "poll_url": "https://example.com",
  "started_at": 0
}
```

## List technique run history

`client.techniques.runs.list(RunListParamsquery?, RequestOptionsoptions?): TechniqueRunsCursorPage<RunListResponse>`

**get** `/technique-runs`

Lists technique run history for the authenticated caller, including pending, running, completed, and failed technique runs. Results are newest first and can be filtered by workspace_id, project_id, technique_id, and status. Each item includes poll_url; use it to poll pending/running technique runs and to fetch completed or failed run details and outputs.

### Parameters

- `query: RunListParams`

  - `cursor?: string`

    Opaque cursor for fetching the next page

  - `limit?: number`

    Maximum number of results to return

  - `project_id?: string`

    Project identifier

  - `status?: "pending" | "running" | "completed" | "failed"`

    Run status filter

    - `"pending"`

    - `"running"`

    - `"completed"`

    - `"failed"`

  - `technique_id?: string`

    Technique identifier

  - `workspace_id?: string`

    Workspace identifier

### Returns

- `RunListResponse`

  - `created_at: number`

  - `progress: number`

  - `project_id: string`

    Project identifier

  - `run_id: string`

    Run identifier

  - `status: "pending" | "running" | "completed" | "failed"`

    - `"pending"`

    - `"running"`

    - `"completed"`

    - `"failed"`

  - `technique: Technique`

    - `name: string`

      Technique name

    - `technique_id: string`

      Technique identifier

  - `technique_run_id: string`

    Run identifier

  - `workspace_id: string`

    Workspace identifier

  - `charged_cost?: number`

    Cost charged in USD

  - `completed_at?: number`

  - `error_code?: string`

    Machine-readable run error code

  - `error_message?: string`

    Human-readable run error message

  - `outputs?: Array<Output>`

    - `output_id: string`

      Run output identifier

    - `type: "imageUrl" | "videoUrl" | "audioUrl" | 2 more`

      Run output media type

      - `"imageUrl"`

      - `"videoUrl"`

      - `"audioUrl"`

      - `"text"`

      - `"documentUrl"`

    - `url: string`

      Run output URL or text content

  - `poll_url?: string`

    URL to poll pending/running runs or fetch completed/failed run details.

  - `started_at?: number`

### Example

```typescript
import FLORA from '@flora-ai/flora';

const client = new FLORA({
  apiKey: process.env['FLORA_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const runListResponse of client.techniques.runs.list()) {
  console.log(runListResponse.project_id);
}
```

#### Response

```json
{
  "meta": {
    "next_cursor": "eyJvZmZzZXQiOjIwfQ",
    "total_estimate": 0
  },
  "technique_runs": [
    {
      "created_at": 0,
      "progress": 0,
      "project_id": "prj_abc123",
      "run_id": "run_abc123",
      "status": "pending",
      "technique": {
        "name": "name",
        "technique_id": "tech_abcd1234"
      },
      "technique_run_id": "run_abc123",
      "workspace_id": "ws_abc123",
      "charged_cost": 0,
      "completed_at": 0,
      "error_code": "provider_error",
      "error_message": "The provider failed to complete the generation.",
      "outputs": [
        {
          "output_id": "output_1",
          "type": "imageUrl",
          "url": "https://media.flora.ai/output.png"
        }
      ],
      "poll_url": "https://example.com",
      "started_at": 0
    }
  ]
}
```

## Get a technique run

`client.techniques.runs.retrieve(stringrunID, RunRetrieveParamsparams, RequestOptionsoptions?): RunRetrieveResponse`

**get** `/techniques/{techniqueId}/runs/{runId}`

Returns status, progress, outputs, and error details for a technique run when it is accessible to the authenticated public API key.

### Parameters

- `runID: string`

  Run identifier

- `params: RunRetrieveParams`

  - `techniqueId: string`

    Technique identifier or slug

### Returns

- `RunRetrieveResponse`

  - `created_at: number`

  - `progress: number`

  - `run_id: string`

    Run identifier

  - `status: "pending" | "running" | "completed" | "failed"`

    - `"pending"`

    - `"running"`

    - `"completed"`

    - `"failed"`

  - `charged_cost?: number`

    Cost charged in USD

  - `completed_at?: number`

  - `error_code?: string`

    Machine-readable run error code

  - `error_message?: string`

    Human-readable run error message

  - `outputs?: Array<Output>`

    - `output_id: string`

      Run output identifier

    - `type: "imageUrl" | "videoUrl" | "audioUrl" | 2 more`

      Run output media type

      - `"imageUrl"`

      - `"videoUrl"`

      - `"audioUrl"`

      - `"text"`

      - `"documentUrl"`

    - `url: string`

      Run output URL or text content

  - `poll_url?: string`

    URL to poll pending/running runs or fetch completed/failed run details.

  - `started_at?: number`

### Example

```typescript
import FLORA from '@flora-ai/flora';

const client = new FLORA({
  apiKey: process.env['FLORA_API_KEY'], // This is the default and can be omitted
});

const run = await client.techniques.runs.retrieve('run_abc123', {
  techniqueId: 'art-directors-critique',
});

console.log(run.run_id);
```

#### Response

```json
{
  "created_at": 0,
  "progress": 0,
  "run_id": "run_abc123",
  "status": "pending",
  "charged_cost": 0,
  "completed_at": 0,
  "error_code": "provider_error",
  "error_message": "The provider failed to complete the generation.",
  "outputs": [
    {
      "output_id": "output_1",
      "type": "imageUrl",
      "url": "https://media.flora.ai/output.png"
    }
  ],
  "poll_url": "https://example.com",
  "started_at": 0
}
```

## Domain Types

### Run Create Response

- `RunCreateResponse`

  - `created_at: number`

  - `progress: number`

  - `run_id: string`

    Run identifier

  - `status: "pending" | "running" | "completed" | "failed"`

    - `"pending"`

    - `"running"`

    - `"completed"`

    - `"failed"`

  - `charged_cost?: number`

    Cost charged in USD

  - `completed_at?: number`

  - `error_code?: string`

    Machine-readable run error code

  - `error_message?: string`

    Human-readable run error message

  - `outputs?: Array<Output>`

    - `output_id: string`

      Run output identifier

    - `type: "imageUrl" | "videoUrl" | "audioUrl" | 2 more`

      Run output media type

      - `"imageUrl"`

      - `"videoUrl"`

      - `"audioUrl"`

      - `"text"`

      - `"documentUrl"`

    - `url: string`

      Run output URL or text content

  - `poll_url?: string`

    URL to poll pending/running runs or fetch completed/failed run details.

  - `started_at?: number`

### Run List Response

- `RunListResponse`

  - `created_at: number`

  - `progress: number`

  - `project_id: string`

    Project identifier

  - `run_id: string`

    Run identifier

  - `status: "pending" | "running" | "completed" | "failed"`

    - `"pending"`

    - `"running"`

    - `"completed"`

    - `"failed"`

  - `technique: Technique`

    - `name: string`

      Technique name

    - `technique_id: string`

      Technique identifier

  - `technique_run_id: string`

    Run identifier

  - `workspace_id: string`

    Workspace identifier

  - `charged_cost?: number`

    Cost charged in USD

  - `completed_at?: number`

  - `error_code?: string`

    Machine-readable run error code

  - `error_message?: string`

    Human-readable run error message

  - `outputs?: Array<Output>`

    - `output_id: string`

      Run output identifier

    - `type: "imageUrl" | "videoUrl" | "audioUrl" | 2 more`

      Run output media type

      - `"imageUrl"`

      - `"videoUrl"`

      - `"audioUrl"`

      - `"text"`

      - `"documentUrl"`

    - `url: string`

      Run output URL or text content

  - `poll_url?: string`

    URL to poll pending/running runs or fetch completed/failed run details.

  - `started_at?: number`

### Run Retrieve Response

- `RunRetrieveResponse`

  - `created_at: number`

  - `progress: number`

  - `run_id: string`

    Run identifier

  - `status: "pending" | "running" | "completed" | "failed"`

    - `"pending"`

    - `"running"`

    - `"completed"`

    - `"failed"`

  - `charged_cost?: number`

    Cost charged in USD

  - `completed_at?: number`

  - `error_code?: string`

    Machine-readable run error code

  - `error_message?: string`

    Human-readable run error message

  - `outputs?: Array<Output>`

    - `output_id: string`

      Run output identifier

    - `type: "imageUrl" | "videoUrl" | "audioUrl" | 2 more`

      Run output media type

      - `"imageUrl"`

      - `"videoUrl"`

      - `"audioUrl"`

      - `"text"`

      - `"documentUrl"`

    - `url: string`

      Run output URL or text content

  - `poll_url?: string`

    URL to poll pending/running runs or fetch completed/failed run details.

  - `started_at?: number`