Reports

A report applies a playbook's questions to a completed analysis and returns scored findings, an executive summary, and recommendations. Agent-based generation splits the analysis into time windows, processes them asynchronously, and assembles sections — poll the status endpoint until the report is COMPLETED, then fetch its windows and sections. Dashboard endpoints aggregate metrics across all reports in a workspace.

All endpoints are scoped to the workspace resolved from your credentials.

Generation flow

1. POST /v1/reports/generate with a playbook_id and analysis_id. The API creates the report with status PENDING, enqueues generation, and returns the report object immediately.
2. Poll GET /v1/reports/{report_id}/status until status is COMPLETED (or FAILED). The progress object tracks window processing.
3. Fetch the finished report via GET /v1/reports/{report_id} (findings included), plus /windows and /sections for the agent-generated breakdown.

Report statuses: PENDING → GENERATING → COMPLETED | FAILED. generation_method is legacy (synchronous, single-pass) or agent_v1 (queued, window-based).

POST /v1/reports/generate

Start report generation for a playbook and an analysis. Requires member access to the playbook's use case. Returns 404 if the analysis is not in your workspace or the playbook does not exist.

Request body

{
  "playbook_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "analysis_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Field	Type	Description
playbook_id	string (UUID)	Playbook whose questions drive the report.
analysis_id	string (UUID)	Completed analysis to report on. Must belong to the active workspace.

Response — the full report object (see report object fields below), initially with status: "PENDING" and empty findings for the agent_v1 path.

curl -X POST https://api.perceive8.com/v1/reports/generate \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"playbook_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "analysis_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'

GET /v1/reports

List reports in the active workspace, newest first. Members with a restricted use-case set see only reports they can view; non-owner users see only their own reports.

Parameters

Name	In	Type	Description
analysis_id	query	string	Optional. Only reports for this analysis.
user_id	query	string	Deprecated; accepted for backwards compatibility and ignored. Scoping is workspace-based.

Response — array of report list items:

[
  {
    "id": "1b4e28ba-2fa1-11d2-883f-0016d3cca427",
    "playbook_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "analysis_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "COMPLETED",
    "overall_assessment": "good",
    "concern_count": {"high": 0, "medium": 2, "low": 1},
    "score": 82,
    "severity_counts": {"high": 0, "medium": 2, "low": 1},
    "sub_scores": {"discovery": 78, "closing": 86},
    "created_at": "2026-08-18T14:03:11",
    "completed_at": "2026-08-18T14:05:02",
    "playbook_name": "Discovery call",
    "use_case_slug": "sales",
    "generation_method": "agent_v1"
  }
]

GET /v1/reports/{report_id}

Get a single report with its findings, sorted by sort_order, and the playbook it was generated from. Requires viewer access to the report's use case. Returns 404 if the report is not in your workspace.

Parameters

Name	In	Type	Description
report_id	path	string (UUID)	Report identifier.

Response — the full report object (fields below).

Report object fields

Field	Type	Description
id	string (UUID)	Report identifier.
playbook_id	string (UUID)	Playbook used.
analysis_id	string (UUID)	Analysis reported on.
user_id	string (UUID)	Internal user who requested the report.
status	string	PENDING, GENERATING, COMPLETED, or FAILED.
executive_summary	string | null	Generated summary text.
overall_assessment	string | null	Overall qualitative assessment.
concern_count	object | null	Concern totals (shape set by the generator).
score	integer | null	Overall score.
severity_counts	object | null	Counts keyed by severity level.
sub_scores	object | null	Per-dimension scores.
error_message	string | null	Failure detail when status is FAILED.
created_at	string (datetime)	Creation time.
completed_at	string (datetime) | null	Completion time.
generation_method	string	legacy or agent_v1.
agent_model	string | null	Model used for agent-based generation.
window_count	integer | null	Total time windows planned.
windows_completed	integer	Windows processed so far.
recommendations	object | null	Generated recommendations.
timeline_highlights	object | null	Key timeline moments.
use_case_slug	string | null	Use case the report belongs to.
total_input_tokens	integer | null	LLM input tokens consumed.
total_output_tokens	integer | null	LLM output tokens consumed.
estimated_cost_usd	number | null	Estimated generation cost.
post_call_actions_status	string | null	Status of post-call action generation.
action_items	object | null	Generated post-call action items.
combined_playbook_ids	array | null	Playbooks combined into this report.
relevance_reasoning	string | null	Why the playbook was considered relevant.
findings	array	One entry per playbook question (see below). Empty while generation is queued.
playbook	object	Embedded playbook: id, name, description, user_id, is_builtin, created_at, updated_at, questions (empty list).

Each entry in findings:

Field	Type	Description
id	string (UUID)	Finding identifier.
question_prompt	string	The playbook question answered.
category	string | null	Question category.
severity_level	string	Severity assigned to the question.
answer	string | null	Generated answer.
concern_detected	boolean	Whether the answer indicates a concern.
evidence	array	Supporting transcript spans: speaker, start_time, end_time, text, relevance_score.
sort_order	integer	Question order within the playbook.

GET /v1/reports/{report_id}/status

Get the current generation status and progress for a report. Requires viewer access to the report's use case. Returns 404 if the report does not exist or its status cannot be resolved.

Response

{
  "report_id": "1b4e28ba-2fa1-11d2-883f-0016d3cca427",
  "status": "GENERATING",
  "generation_method": "agent_v1",
  "progress": {
    "window_count": 6,
    "windows_completed": 2,
    "current_window": 3,
    "percent": 33.3
  },
  "estimated_remaining_seconds": null
}

estimated_remaining_seconds is currently always null. progress fields are null for reports that have not started window processing.

GET /v1/reports/{report_id}/windows

Get all time windows produced by agent-based generation. Requires viewer access. Returns an empty list for legacy reports and when the report service is unavailable.

Response

[
  {
    "id": "9f8c7d6e-5b4a-4c3d-8e2f-1a0b9c8d7e6f",
    "report_id": "1b4e28ba-2fa1-11d2-883f-0016d3cca427",
    "window_index": 0,
    "start_time": 0.0,
    "end_time": 300.0,
    "window_summary": "Opening, agenda, and discovery questions.",
    "concerns": [
      {"type": "objection", "severity": "medium", "description": "Budget concern raised", "timestamp": 212.5}
    ],
    "speaker_dynamics": {"rep_talk_ratio": 0.62},
    "key_moments": [{"timestamp": 45.0, "label": "Pricing discussed"}],
    "created_at": "2026-08-18T14:03:40"
  }
]

concerns items carry type, severity, description, and timestamp. speaker_dynamics and key_moments are generator-defined structures and may be null.

GET /v1/reports/{report_id}/sections

Get the assembled report sections. Requires viewer access. Returns an empty list for legacy reports and when the report service is unavailable.

Response

[
  {
    "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
    "report_id": "1b4e28ba-2fa1-11d2-883f-0016d3cca427",
    "section_type": "executive_summary",
    "title": "Executive summary",
    "content": "The call covered discovery and pricing...",
    "data": null,
    "sort_order": 0,
    "created_at": "2026-08-18T14:05:02"
  }
]

section_type is one of executive_summary, timeline, concerns, recommendations, or speaker_analysis. content holds prose; data holds the structured payload for sections that have one.

GET /v1/reports/{report_id}/actions

Get the generated post-call action items for a report. Requires viewer access. Returns 404 if the report is not in your workspace.

Response

{
  "report_id": "1b4e28ba-2fa1-11d2-883f-0016d3cca427",
  "post_call_actions_status": "COMPLETED",
  "action_items": [
    {"title": "Send pricing follow-up", "owner": "rep"}
  ]
}

action_items is the items list from the stored action-items payload (or the payload itself when it is not wrapped in an items key); empty when no actions were generated.

DELETE /v1/reports/{report_id}

Delete a report from the active workspace. Requires member access to the report's use case. Returns 204 No Content on success and 404 if the report is not in your workspace. A user_id query parameter is accepted for backwards compatibility and ignored.

curl -X DELETE https://api.perceive8.com/v1/reports/1b4e28ba-2fa1-11d2-883f-0016d3cca427 \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx"

Dashboards

Dashboard endpoints aggregate metrics across the reports in your workspace. Each requires a minimum workspace role: the viewer dashboard level maps to the workspace user role. Non-manager callers automatically see only their own data.

GET /v1/reports/insights/dashboard

Aggregate behavioral insights across reports: KPIs, behavior correlations, win/loss patterns, leverage ranking, top-performer fingerprint, adoption trends, and an LLM-generated narrative.

Parameters

Name	In	Type	Description
scope	query	string	team (default) or rep. rep restricts the aggregation to the calling user; non-managers are always restricted to their own data.

Response

Field	Type	Description
kpi	object	Headline KPI values.
behaviors	array	Per-behavior metrics: id, label, adoptionRate, bookingWith, bookingWithout, lift, n, confidence, weekly (list of numbers).
winLoss	array	Win/loss pattern entries.
leverage	array	Behavior leverage ranking.
fingerprint	array	Top-performer fingerprint entries.
adoptionSeries	array	Adoption trend series.
narrative	object	LLM-generated narrative.

GET /v1/reports/calls/dashboard

Aggregate call-quality metrics across reports: score trends, a leaderboard, missed checklist items, and per-analysis enrichment for peek rows. Takes no query parameters.

Response

Field	Type	Description
scoreSeries	array of numbers	Score trend over time.
leaderboard	array	Per-rep ranking entries.
missed	array	Most-missed checklist items.
checklist	array	Checklist item performance.
momentsByAnalysis	object	Map of analysis ID to key-moment lists.
missedByAnalysis	object	Map of analysis ID to missed-item lists.

GET /v1/reports/compliance/dashboard

Aggregate compliance metrics across reports, optionally filtered by playbook and time window.

Parameters

Name	In	Type	Description
playbook_id	query	string (UUID)	Optional. Only reports from this playbook. Invalid values return 400.
start	query	string	Optional ISO 8601 start datetime (inclusive window start). Invalid values return 400.
end	query	string	Optional ISO 8601 end datetime. Invalid values return 400.
user_id	query	string	Deprecated; accepted for backwards compatibility and ignored. Scoping is workspace-based.

Response

Field	Type	Description
summary	object	Headline compliance totals.
derived	object	Derived compliance metrics.
violations	array	Detected violation entries.
byRep	array	Compliance metrics grouped by rep.
trail	array	Compliance trend over time.
sevWeight	object	Severity weighting used in scoring.
isMock	boolean	true when the response is mock/fallback data rather than real aggregates.

curl "https://api.perceive8.com/v1/reports/compliance/dashboard?start=2026-08-01T00:00:00Z&end=2026-08-31T23:59:59Z" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx"