---
title: "One-shot Fi run for testing without the UI"
method: POST
path: "/v4/fi/run"
tags: ["v4", "Fi Run"]
---

# One-shot Fi run for testing without the UI

`POST /v4/fi/run`

Block until Fi completes; persist a `[API run]` fi_thread for debugging.

## Request body

- FiRunRequest — One-shot Fi run for testing without the UI.
  - `prompt` string, required — User message to send to Fi
  - `model` string, nullable — Claude model override (e.g. 'claude-sonnet-4-6'). Defaults to Fi's standard model.
  - `sandboxTier` 'small' | 'medium' | 'large'
  - `tableIntegrationId` string, nullable — Table integration to mount (DuckLake/DuckDB). Defaults to team's primary.
  - `cubeIntegrationId` string, nullable — Cube integration to mount
  - `applicationContext` string, nullable — Free-form context appended to the prompt (e.g. 'Caller: API smoke test for Vertex pin').

## Response `200`

Success

- SuccessResponseFiRunResponse
  - `success` true, required — Flag for it request was successful
  - `data` FiRunResponse, required — Result of a one-shot Fi run.
    - `success` boolean, required — Whether the run completed successfully
    - `threadId` string, required — fi_threads row ID created for this run; viewable in the Fi UI
    - `sandboxId` string, nullable — E2B sandbox ID used for the run
    - `message` string — Human-readable status message
    - `rawOutput` string — Raw stdout from Claude Code
    - `executionTime` number — Wall-clock execution time in seconds
    - `error` string, nullable — Error message if the run failed
  - `meta` ResponseMeta
    - `requestId` string — Unique request identifier for tracing
    - `timestamp` string, date-time — Response timestamp (UTC)
    - `durationMs` integer, nullable — Request processing time in milliseconds

## Other responses

- `401` — Auth Invalid Token
- `403` — Forbidden Insufficient Permissions
- `422` — Validation Failed
- `426` — Business Quota Exceeded
- `500` — Internal Error
- `502` — External Service Error
- `503` — External Service Unavailable
- `504` — External Service Timeout

---

[API](https://skmtc.dev/definite/apis/defapi.md) · [All operations](https://skmtc.dev/definite/apis/defapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/definite/defapi/revisions/5ea378187147/schema)