AI Agents

OpenScouter uses a pipeline of AI agents to process session data. Each agent has a distinct role:

Agent	Endpoint	Role
Agent 1	POST /api/ai	Real-time analysis during a test session
Agent 3	POST /api/reports	Generate a full post-session report
Agent 4	POST /api/reports/job/:id	Aggregate reports across all sessions of a study

Agents run asynchronously. Each endpoint returns a job ID you can use to poll for results.

Endpoints

POST /api/ai JWT

Trigger Agent 1 real-time analysis for an active session

Agent 1 processes behavioral, facial, and voice signals as they arrive during a session. Call this endpoint to request an intermediate analysis snapshot without waiting for the session to complete.

Request body

{
  "sessionId": "sess_001",
  "includeSignals": ["events", "facial", "voice"],
  "snapshotAt": "2026-03-16T10:20:00Z"
}

Field	Type	Required	Description
sessionId	string	Yes	ID of the active session to analyze
includeSignals	array of strings	No	Which signal types to include. Defaults to all available.
snapshotAt	string (ISO 8601)	No	Analyze data up to this timestamp. Defaults to now.

Response

{
  "success": true,
  "data": {
    "analysisJobId": "ajob_001",
    "sessionId": "sess_001",
    "status": "queued",
    "estimatedCompletionSeconds": 20
  },
  "error": null,
  "metadata": null
}

When complete, the analysis result is attached to the session and accessible via GET /api/sessions/:id.

Analysis result shape (when resolved)

{
  "analysisJobId": "ajob_001",
  "status": "complete",
  "insights": {
    "overallFrustrationScore": 0.42,
    "attentionDropTimestamps": ["2026-03-16T10:14:31.000Z"],
    "criticalMoments": [
      {
        "timestamp": "2026-03-16T10:14:30.000Z",
        "type": "hesitation_cluster",
        "severity": "high",
        "context": "Checkout flow - payment step"
      }
    ],
    "summary": "Tester encountered significant confusion at the payment step. Attention dropped sharply at 10:14:31 and frustration peaked before recovery."
  }
}

POST /api/reports JWT

Trigger Agent 3 to generate a full post-session report

Agent 3 runs after a session is marked completed. It combines all signal data to produce a comprehensive report with findings, severity ratings, and actionable recommendations.

Request body

{
  "sessionId": "sess_001",
  "reportFormat": "structured",
  "includeScreenshots": true
}

Field	Type	Required	Description
sessionId	string	Yes	ID of the completed session
reportFormat	string	No	structured (default) or narrative
includeScreenshots	boolean	No	Whether to include annotated frame captures. Defaults to false.

Response

{
  "success": true,
  "data": {
    "reportJobId": "rjob_001",
    "sessionId": "sess_001",
    "status": "queued",
    "estimatedCompletionSeconds": 60
  },
  "error": null,
  "metadata": null
}

Report result shape (when resolved)

{
  "reportJobId": "rjob_001",
  "status": "complete",
  "reportId": "rep_001",
  "report": {
    "sessionId": "sess_001",
    "generatedAt": "2026-03-16T10:45:00Z",
    "overallScore": 67,
    "findings": [
      {
        "findingId": "f_001",
        "severity": "critical",
        "title": "Payment step caused task abandonment risk",
        "description": "Tester spent 48 seconds at the payment step with high confusion signals before proceeding.",
        "timestamp": "2026-03-16T10:14:30.000Z",
        "affectedFlow": "Checkout"
      }
    ],
    "recommendations": [
      "Add inline help text to the CVV field.",
      "Reduce the number of fields on the payment form."
    ],
    "emotionalProfile": {
      "avgFrustration": 0.31,
      "avgConfusion": 0.22,
      "avgPositive": 0.47
    }
  }
}

POST /api/reports/job/:id JWT

Trigger Agent 4 to generate an aggregated report across all sessions of a study

Path parameters

Parameter	Description
id	Study (job) ID

Agent 4 aggregates individual session reports into a study-level summary. It identifies patterns across testers, computes comparative metrics between A/B variants, and produces prioritized findings.

Request body

{
  "includeVariantComparison": true,
  "minSessionCount": 3
}

Field	Type	Required	Description
includeVariantComparison	boolean	No	Whether to include A/B variant breakdown. Defaults to true if variants exist.
minSessionCount	integer	No	Minimum number of sessions required to generate the report. Defaults to 1.

Response

{
  "success": true,
  "data": {
    "aggregateJobId": "aggjob_001",
    "jobId": "job_abc123",
    "sessionCount": 12,
    "status": "queued",
    "estimatedCompletionSeconds": 120
  },
  "error": null,
  "metadata": null
}

Aggregate report shape (when resolved)

{
  "aggregateJobId": "aggjob_001",
  "status": "complete",
  "aggregateReportId": "arep_001",
  "report": {
    "jobId": "job_abc123",
    "sessionCount": 12,
    "generatedAt": "2026-03-16T11:00:00Z",
    "studyScore": 72,
    "topFindings": [
      {
        "findingId": "af_001",
        "severity": "critical",
        "title": "Checkout confusion affects 75% of testers",
        "affectedSessionCount": 9
      }
    ],
    "variantComparison": {
      "A": { "avgScore": 68, "sessionCount": 6 },
      "B": { "avgScore": 76, "sessionCount": 6 }
    },
    "recommendations": [
      "Variant B's simplified payment form performs significantly better. Consider promoting it to all users."
    ]
  }
}