Generate Reports

This guide shows you how to read automatically rendered reports from a completed analysis run and explicitly re-render a different presentation when needed.

Report creation changes presentation only. It does not run video analysis again or change the answers, evidence, result states, limitations, or provenance.

Before You Start

You need:

• A run whose status is completed.
• The run ID in RUN_ID.
• RUN_WORKFLOWS permission to create a report. Reading reports requires VIEW_INSIGHTS.

Re-render A Report

The API automatically renders the requested report formats when an analysis run reaches completed, using the stored report-template snapshot. Use the endpoint below only when you need a different presentation from the same stored answers. Send an inline report_template and choose one or more output formats:

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/runs/$RUN_ID/reports" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: report-rerender-01" \
  -d '{
    "report_template": {
      "language": "en",
      "blocks": [
        {"type":"timeline","answer_key":"inspection_timeline","label":"Activity timeline"},
        {"type":"narrative","answer_key":"inspection_summary","label":"Summary"}
      ]
    },
    "formats": ["json", "markdown"]
  }'

The explicit re-render response is 201 Created. It reads stored answers and changes presentation only; it does not run video analysis again. Use a new Idempotency-Key for each new report request. Reuse the same key only when retrying the same request.

Retrieve Reports

List reports for the run:

curl --fail-with-body --get "$BASE_URL/api/v1alpha1/reports" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  --data-urlencode "run_id=$RUN_ID"

Retrieve one report:

curl --fail-with-body --get "$BASE_URL/api/v1alpha1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  --data-urlencode "expand[]=content" \
  --data-urlencode "expand[]=manifest"

Report metadata is returned by default. expand[]=content returns the rendered artifact. expand[]=manifest returns its trust bindings with fresh signed evidence URLs. When signed evidence URLs are present, evidence_urls_expire_at gives their expiry time in the manifest and in each binding that contains URLs. Keep the evidence ID and call GET /api/v1alpha1/evidence/{evidence_id} when a URL expires; the endpoint returns 302 Found with a fresh signed media URL and Cache-Control: no-store. Do not treat a signed URL as a durable evidence identifier. Repeat expand[] as shown when you need both.

Keep Reports Verifiable

Preserve the full manifest when storing or exporting a report. Each manifest.bindings[] entry carries result_state, limitations, evidence_refs, evidence_urls, and provenance_refs. A claim is incomplete if a reviewer cannot trace it to its evidence.

For reusable templates, block types, sorting, grouping, and JSON mappings, continue to Customize report layouts.