# Agents API

> Create, run, and manage scheduled AI agents under /api/agents.

*[View this page in the Flax docs](https://flax-analytics.com/docs/api-reference/agents)*

Agents are scheduled, evidence-grounded LLM jobs: they analyze your data on a cadence
and emit outputs. Listing needs the `read` scope; creating/updating/running need
`write` and an **org-admin** service account; deleting needs `manage`. Each run spends
LLM tokens against the org's budget.

## List and get

- `GET /api/agents` — the org's agents.
- `GET /api/agents/{agentId}` — one agent (its instructions, model, grounding, cadence,
  and outputs). Use as a template for updates.

## Create and update

- `POST /api/agents` — create an agent. `instructions` is the task prompt; `grounding`
  is the resources a run may read as evidence; `outputs` is what it produces; `cadence`
  is like a [schedule](/docs/api-reference/schedules). Bound cost with `maxTokensPerRun`
  and `maxRounds`.
- `PUT /api/agents/{agentId}` — replace its fields.
- `PATCH /api/agents/{agentId}/active` — pause or resume its schedule (`{"active": false}`).

## Run and inspect

- `POST /api/agents/{agentId}/run` — run it now (async); returns a `runId`. Spends tokens.
- `GET /api/agents/{agentId}/runs` — the agent's recent runs and their outputs.

## Delete

`DELETE /api/agents/{agentId}` — remove the agent and its run history (`manage`).

## Related

- [Scheduled deliveries](/docs/automation-ai/scheduled-deliveries)