Analytics

Re-run the AI analysis of a finished call on demand. Every call is already analysed after it ends, so reporting does not need these.

Generate a detailed call report

POST /analytics/analyze

Runs a paid AI analysis of a transcript you supply against the agent instructions you supply and stores it as the call’s detailed report (classification, metrics, prompt adherence, sentiment flow, key moments, action items, summary). The room must belong to the API key’s organisation. If a report already exists for the call it is returned without a new analysis; a failed analysis is final (502 on every later request). Rate limited per host and per key (20 per minute by default).

Scope: analytics:read

Body (application/json)

Field	Type	Required	Description
room_name	string	yes	Call ID (room name) to attach the report to.
transcriptText	string	yes	Transcript text to analyse. Taken as given; it is not read from the stored call.
instructions	string	no	Agent instructions to judge adherence against. Optional, defaults to empty.

Example request

curl -X POST "https://api.foan.ai/api/v1/analytics/analyze" \
  -H "Authorization: Bearer $FOAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"room_name":"call-7f3a9c2e","transcriptText":"Agent: Hi Priya, this is Nina calling about your recent order.\nCustomer: Haan, boliye.\n...","instructions":"Confirm the order and the delivery address, then thank the customer."}'

Response 200

{
  "success": true,
  "data": {
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2",
    "roomName": "call-7f3a9c2e",
    "instructions": "Confirm the order and the delivery address, then thank the customer.",
    "transcriptText": "Agent: Hi Priya, this is Nina calling about your recent order.\nCustomer: Haan, boliye.\n...",
    "parsedAnalysis": {
      "call_classification": {
        "primary_type": "support",
        "subtype": "order_confirmation",
        "confidence": 0.93
      },
      "universal_metrics": {
        "duration_minutes": 2,
        "total_speakers": 2,
        "word_count": 240
      },
      "dynamic_metrics": [
        {
          "name": "Resolution",
          "value": 90,
          "max": 100,
          "indicator": "good"
        }
      ],
      "prompt_adherence": {
        "overall_score": 88,
        "followed": [
          "Confirmed the address"
        ],
        "ignored": [],
        "impact_on_outcomes": "High adherence led to a clean confirmation.",
        "prompt_improvements": [
          "Ask for a preferred delivery slot"
        ],
        "correlation": {
          "adherence_to_satisfaction": 0.8,
          "critical_misses": []
        }
      },
      "sentiment_flow": [
        {
          "time": "Opening",
          "sentiment": 60,
          "label": "Opening"
        },
        {
          "time": "Closing",
          "sentiment": 80,
          "label": "Closing"
        }
      ],
      "speaker_distribution": [
        {
          "speaker": "Agent",
          "percentage": 55,
          "turns": 8
        },
        {
          "speaker": "Customer",
          "percentage": 45,
          "turns": 6
        }
      ],
      "key_moments": [
        {
          "time": "mid-call",
          "type": "confirmation",
          "description": "Customer confirmed the address"
        }
      ],
      "action_items": [
        {
          "owner": "Agent",
          "task": "Dispatch the order",
          "priority": "high"
        }
      ],
      "summary": "Order and address confirmed; dispatch today.",
      "insights": [
        "Customer prefers evening delivery"
      ],
      "risk_flags": [],
      "next_steps": "Dispatch the order"
    },
    "tokenUsage": {
      "prompt_tokens": 1850,
      "completion_tokens": 620,
      "total_tokens": 2470
    },
    "model": "analysis-model",
    "createdAt": "2026-09-24T09:40:00.000Z",
    "updatedAt": "2026-09-24T09:40:00.000Z"
  }
}

Errors

Code	When
400	room_name or transcriptText missing. Body: {success:false, message}.
401	Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation.
403	Missing analytics:read scope.
404	No call with that room name in your organisation.
429	Rate limited.
502	The analysis could not be completed; this is final for this call.

Re-run the call overview

POST /analytics/analyze-overview

Runs a paid AI analysis of a call’s stored transcript and returns the overview (score 1-10, Relevant/Irrelevant, customer sentiment, up to 3 summary bullets) and the customer’s final result with a verified quote. The new overview replaces the one stored on the call; the call’s agent result (its outcome on the Results page) is not re-run. The call must belong to the API key’s organisation. Rate limited per host and per key (20 per minute by default).

Scope: analytics:read

Body (application/json)

Field	Type	Required	Description
roomName	string	yes	Call ID (room name).

Example request

curl -X POST "https://api.foan.ai/api/v1/analytics/analyze-overview" \
  -H "Authorization: Bearer $FOAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"roomName":"call-7f3a9c2e"}'

Response 200

{
  "success": true,
  "data": {
    "overview": {
      "score": 8,
      "classification": "Relevant",
      "user_sentiment": "Interested",
      "summary": [
        "Called to confirm order delivery address.",
        "Customer confirmed the address.",
        "Order will be dispatched today."
      ]
    },
    "result": {
      "code": "interested",
      "quote": "Haan, same address pe bhej do",
      "quote_en": "Yes, send it to the same address",
      "callback_time": null,
      "evidence_status": "verified"
    },
    "agentResult": null,
    "tokenUsage": {
      "prompt_tokens": 1450,
      "completion_tokens": 140,
      "total_tokens": 1590
    }
  }
}

Errors

Code	When
400	roomName missing.
401	Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation.
403	Missing analytics:read scope.
404	Call not found, not in your organisation, or it has no transcript.
429	Rate limited.
500	Unexpected server error.