---
title: "Run Agent"
method: POST
path: "/api/v1/agent/run"
tags: ["Agent"]
---

# Run Agent

`POST /api/v1/agent/run`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/agent/run`
- Auth: HTTP bearer

Runs a single Floqer Nova web-agent request synchronously and returns the result. Provide a natural-language `prompt` and, optionally, an `output_schema` describing the JSON fields you want back. Requests typically take 10-60 seconds; the request stays open until the agent finishes. Billing: one Floqer Nova charge per request. Any 5xx response is automatically refunded — a 5xx means you were not charged. Every response (success or error) includes a `request_id` (e.g. `fl_…`) — quote it when contacting support. Error codes: INVALID_REQUEST, INVALID_OUTPUT_SCHEMA (400); UNAUTHORIZED (401); INSUFFICIENT_CREDITS (402); ROLE_FORBIDDEN, INSUFFICIENT_SCOPE (403); RATE_LIMITED (429); AGENT_INTERNAL_ERROR, AGENT_EXECUTION_FAILED (500); AGENT_BUSY (503); AGENT_TIMEOUT (504).

## Request body

- object
  - `prompt` string, required: Natural-language instruction for the web agent.
  - `output_schema` object: Optional JSON-schema-style object describing the structured output. Shape: `{ "properties": { "<field>": { "type": "string", "description": "..." } } }`. Supported field types: string, number, integer, boolean, array, object. Max 20 fields. When omitted, the full answer is returned under a single `result` field.

## Response `200`

Agent completed successfully.

- object: Agent completed successfully.
  - `status` integer
  - `data` object: Structured output keyed by your output_schema fields, or `{ result }` when no schema given.
  - `citations` object[]: Web sources the agent consulted.
  - `request_id` string: Unique id for this request (e.g. fl_…). Quote it when contacting support.

## Other responses

- `400`: Invalid request body or output schema.
- `401`: Unauthorized (UNAUTHORIZED) — missing or invalid API key.
- `402`: Insufficient credits — INSUFFICIENT_CREDITS.
- `403`: Your role (ROLE_FORBIDDEN) or the API key (INSUFFICIENT_SCOPE) lacks the agent:run scope.
- `429`: Rate limited (RATE_LIMITED) — agent calls have their own org-level quota, separate from general API limits.
- `500`: Agent failed (AGENT_INTERNAL_ERROR / AGENT_EXECUTION_FAILED). Not charged.
- `503`: Agent at capacity (AGENT_BUSY). Not charged; retry after `Retry-After`.
- `504`: Agent timed out (AGENT_TIMEOUT). Not charged.

---

[API](https://skmtc.dev/floqer/apis/floqer-public-api.md) - [All operations](https://skmtc.dev/floqer/apis/floqer-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/floqer/apis/floqer-public-api/revisions/fce50dc07b20?raw)