---
title: "Run Qa Agent"
method: POST
path: "/v2/qa-agents/{agent_id}/run"
tags: ["qa-agents"]
---

# Run Qa Agent

`POST /v2/qa-agents/{agent_id}/run`

Run a QA agent against the requested subject traces.

## Path parameters

- `agent_id` string, uuid, required

## Request body

- QaAgentRunRequest
  - `trace_ids` string[], required
  - `overwrite` boolean
  - `batch_id` string, uuid, nullable

## Response `200`

Successful Response

- QaAgentResultResponse[]
  - `result` object, nullable
  - `canonical_result` QaAgentResultV1 — Versioned result every QA agent must emit.
    - `schema_version` 'qa_agent_result.v1', required
    - `verdict` 'passed' | 'failed' | 'unknown', required
    - `findings` QaAgentFinding[], required
      - `finding_type` string, required
      - `severity` 'info' | 'warning' | 'error', required
      - `summary` string, required
      - `confidence` number, nullable
      - `evidence_refs` string[]
      - `recommended_action` string, nullable
      - `metadata` object
    - `summary` string, nullable
    - `metadata` object
  - `canonical_verdict` 'passed' | 'failed' | 'unknown', nullable
  - `id` string, uuid, required
  - `subject_type` 'trace' | 'environment' | 'taskset' | 'task' — Canonical resources a QA agent can analyze.
  - `subject_id` string, uuid, required
  - `subject_trace_id` string, uuid, nullable, required
  - `subject_snapshot` object, nullable
  - `snapshot_hash` string, nullable
  - `attempt` integer
  - `qa_agent_id` string, uuid, required
  - `analysis_trace_id` string, uuid, required
  - `model_id` string, uuid, required
  - `status` 'queued' | 'completed' | 'error' | 'cancelled', required
  - `error` string, nullable
  - `batch_id` string, uuid, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400` — Invalid or malformed request
- `401` — Missing or invalid credentials
- `403` — Caller may not access this resource
- `404` — Referenced entity does not exist
- `409` — Resource already exists
- `422` — Validation Error

## Changes

- **2026-09-25** `44153c2e35e9` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/hud/apis/hud-platform/changes/v2/qa-agents/:agent_id/run/post.md)

---

[API](https://skmtc.dev/hud/apis/hud-platform.md) · [All operations](https://skmtc.dev/hud/apis/hud-platform/llms.txt) · [OpenAPI document](https://skmtc.dev/hud/apis/hud-platform/revisions/50a2fbc0a044?raw)