> ## Documentation Index
> Fetch the complete documentation index at: https://trygradient.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow

> Execute AI workflow runs during assessments

# Workflow

Workflow endpoints allow candidates to run and iterate on AI workflow prompts during multi-phase assessments. The workflow executes a candidate-authored prompt against inbox data and returns the generated output.

## Run Workflow

```
POST /api/workflow/run
```

Executes the candidate's workflow prompt against the inbox emails for the current phase. The workflow runs as a tool-calling agent: it is given `search_email`, `list_emails`, and `get_email` tools (backed by the session's phase inbox via `InboxConnector`) and loops until it produces a final summary output. Uses a fast model (gpt-4o-mini or claude-haiku) for quick iteration. Rate-limited to 10 runs per session.

<Note>This endpoint is authenticated via the candidate session token, not an API key. The session is resolved from that token — there is no `sessionId` body field.</Note>

<ParamField body="skillInstructions" type="string" required>
  The workflow prompt to execute as the system prompt
</ParamField>

<ParamField body="phaseIndex" type="integer">
  Current phase index. Used to load the correct inbox data when multiple phases have different email sets.
</ParamField>

<Accordion title="Response">
  ```json theme={null}
  {
    "output": "## Weekly Deal Flow & Priority Digest\n\n...",
    "runNumber": 1,
    "maxRuns": 10
  }
  ```
</Accordion>

<Accordion title="Error — Rate limited (429)">
  ```json theme={null}
  {
    "error": {
      "code": "rate_limited",
      "message": "Workflow run limit reached (10 runs per session)."
    }
  }
  ```
</Accordion>

***

## Export Workflow Deliverable

```
GET /api/workflow/export
```

Exports the workflow deliverable for a session as a markdown file. Contains the final edited prompt, full run history (each prompt + output pair with timestamps), and any tool-call events logged during workflow runs. Used by admins to download a candidate's workflow work.

<ParamField query="sessionId" type="string" required>
  The assessment session ID
</ParamField>

<ParamField query="phaseId" type="string">
  Target a specific phase (for multi-phase assessments). When omitted, resolves the current/only phase.
</ParamField>

<Accordion title="Response">
  Returns a `.md` file download with `Content-Type: text/markdown; charset=utf-8`.
</Accordion>

<Accordion title="Error — No deliverable found">
  ```json theme={null}
  {
    "error": "No workflow deliverable found for this session."
  }
  ```
</Accordion>