Docs / rag-runs-api

RAG security runs API

← All docs

RAG security scans drive the configured retrieval pipeline with canary-poisoned documents, cross-tenant probes, and prompt-injection payloads, then record which guardrails caught them.

GET /api/v2/rag-runs

curl -sS "https://penaxtra.com/api/v2/rag-runs" \
  -H "Authorization: Bearer $TOKEN"

Required scope: rag:read.

Response

{
  "data": [
    {
      "id": "<uuid>",
      "ai_asset_id": "<uuid>",
      "trigger": "scheduled",
      "started_at": "2026-05-22T10:14:00Z",
      "completed_at": "2026-05-22T10:18:33Z",
      "status": "completed",
      "tests_run": 13,
      "tests_passed": 11,
      "tests_failed": 1,
      "tests_skipped": 1,
      "duration_ms": 273512
    }
  ]
}

Fields

FieldNotes
idRun UUID.
ai_asset_idThe RAG pipeline asset this run targeted (retriever + vector store + corpus).
triggerscheduled, manual.
started_at / completed_atWall-clock timestamps.
statusrunning, completed, failed.
tests_run / tests_passed / tests_failed / tests_skippedSums across the canary, isolation, and injection suites.
duration_msEnd-to-end runtime in milliseconds.

POST /api/v2/rag-runs

curl -sS -X POST "https://penaxtra.com/api/v2/rag-runs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ai_asset_id": "<uuid>"}'

Required scope: rag:write. Returns 202 Accepted. The scan is enqueued asynchronously; poll /api/v2/rag-runs for status.

Response

{
  "accepted": true,
  "ai_asset_id": "<uuid>",
  "poll": "/api/v2/rag-runs"
}

Errors

CodeBodyReason
400{"error":"invalid_ai_asset_id"}ai_asset_id is missing or not a UUID.
404{"error":"rag_asset_not_found"}The asset does not exist in your tenant or is not a RAG system.
413{"error":"payload_too_large","limit_bytes":1048576}Request body exceeded the 1 MiB cap.
429{"error":"rate_limited","retry_after_seconds":N}Tighter cap of six triggers per asset per hour.
502{"error":"enqueue_failed"}The internal scan worker rejected the enqueue request. Retry after a short backoff.

Notes

  • Newest run first; result set capped at 100 rows.
  • A failed test does not mean a guardrail malfunction. Read the matching findings row for the leak category, severity, and mitigation pointer.

Related

Last reviewed: 2026-06-13. Reviewed by: Engineering. Content type: Developer documentation. Reach the maintainers: [email protected] .