Docs / cloud-posture-runs-api

Cloud posture runs API

← All docs

Cloud-posture scans evaluate IAM, network, storage, and AI-service configuration in the cloud accounts your tenant has connected. Each cloud_posture_run is one execution of the configured check set against a single integration.

GET /api/v2/cloud-posture-runs

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

Required scope: cloud_posture:read.

Response

{
  "data": [
    {
      "id": "<uuid>",
      "integration_id": "<uuid>",
      "trigger": "scheduled",
      "started_at": "2026-05-22T10:14:00Z",
      "completed_at": "2026-05-22T10:14:48Z",
      "status": "completed",
      "asset_count": 412,
      "finding_count": 11,
      "duration_ms": 48211
    }
  ]
}

Fields

FieldNotes
idRun UUID. Use this to correlate with the audit log and downstream findings rows.
integration_idThe connected cloud account this run targeted.
triggerscheduled, manual, or verify (a configuration probe that does not persist findings).
started_at / completed_atWall-clock timestamps from the scan worker.
statusrunning, completed, failed, cancelled.
asset_countTotal cloud assets inspected (IAM roles, buckets, network rules, AI services).
finding_countCount of findings emitted by this run. Drill into /api/v2/findings?scan_id=<id> for detail.
duration_msEnd-to-end runtime in milliseconds.

POST /api/v2/cloud-posture-runs

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

Required scope: cloud_posture:write. Returns 202 Accepted with the integration id, the resolved trigger, and a poll URL for run status.

Response

{
  "accepted": true,
  "integration_id": "<uuid>",
  "trigger": "manual",
  "poll": "/api/v2/cloud-posture-runs"
}

Errors

CodeBodyReason
400{"error":"invalid_integration_id"}integration_id is missing or not a UUID.
404{"error":"integration_not_found"}The integration does not exist in your tenant.
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 two manual triggers per integration per twenty-four hours. The Retry-After header carries the same number.
502{"error":"enqueue_failed"}The internal scan worker rejected the enqueue request. Retry after a short backoff.

Audit

Every POST is recorded as an api.call row carrying the token id, method, path, response status, and duration. Use the audit log API (planned) or the in-console audit view to reconcile API-driven runs with their downstream findings.

Notes

  • Newest run first; result set capped at 100 rows.
  • Findings produced by this run share the same scan_id; use the findings endpoint to fetch them with the same control-ID mapping that the console renders.

Related

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