Skip to content
FoanFoanFoan Docs

Results

What each agent achieved on its calls, in the outcomes and details the agent tracks (its resultsConfig or call flow): totals, rows and CSV export. Needs calls:read.

Summarise an agent’s call results

Section titled “Summarise an agent’s call results”

GET /voice/agents/{agentId}/results/summary

Counts one agent’s calls in a date range by the outcomes the agent tracks (its resultsConfig), plus total calls and minutes. Only placed calls that have ended count: scheduled calls not yet placed are left out, and so are calls still ringing or in progress unless they started more than 2 hours ago. Calls with no outcome, or with an outcome the agent no longer tracks, are counted under no_result. The agent must belong to the API key’s organisation. Read only.

Scope: calls:read

Parameters

Name In Type Required Description
agentId path string yes Agent ID.
from query string no Start of the range, inclusive. A date (2026-09-01, read as midnight UTC) or an ISO-8601 timestamp. Defaults to 30 days before to.
to query string no End of the range, exclusive. A bare date includes that whole day (UTC). Defaults to now. Must be after from.
source query string: campaign, inbound, api, manual, widget, unknown no Call source. Unknown means the source was not recorded, never an inferred API call.
useCase query string no Exact use-case key from summary.useCases. Keys are use:<name>, campaign:<id>, line:<receiving-number>, or unlabelled.
search query string no Case-insensitive match on contact name or phone. Outcome is ignored so all outcome totals stay visible.

Example request

Terminal window
curl -X GET "https://api.foan.ai/api/v1/voice/agents/{agentId}/results/summary" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "calls": 128,
    "minutes": 214.6,
    "outcomes": [
      {
        "key": "booked",
        "label": "Booked",
        "count": 41
      },
      {
        "key": "not_interested",
        "label": "Not interested",
        "count": 37
      },
      {
        "key": "transferred_to_human",
        "label": "Transferred to human",
        "count": 9
      },
      {
        "key": "no_result",
        "label": "No result",
        "count": 41
      }
    ],
    "fields": [
      {
        "key": "party_size",
        "label": "Party size",
        "type": "number"
      },
      {
        "key": "transferred_to",
        "label": "Transferred to",
        "type": "phone"
      }
    ]
  }
}

Errors

Code When
400 from or to is not a date, or from is not before to.
401 Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation.
403 The key lacks the calls:read scope, or the agent belongs to another organisation.
404 Agent not found or deleted.
429 Rate limited

List an agent’s call results

Section titled “List an agent’s call results”

GET /voice/agents/{agentId}/results

Lists one agent’s calls in a date range, newest first, each with its outcome and the details noted down on the call. Same calls as the summary (placed calls that have ended). A FLOW agent’s result comes from the flow itself; otherwise it comes from the AI analysis that runs after each call, so a call that just ended may show No result for a minute or two. Filter by outcome or search by name or phone. The agent must belong to the API key’s organisation. Read only.

Scope: calls:read

Parameters

Name In Type Required Description
agentId path string yes Agent ID.
from query string no Start of the range, inclusive. A date (2026-09-01, read as midnight UTC) or an ISO-8601 timestamp. Defaults to 30 days before to.
to query string no End of the range, exclusive. A bare date includes that whole day (UTC). Defaults to now.
outcome query string no Only calls with this outcome key. Must be one the agent tracks, or no_result (no outcome, or one the agent no longer tracks).
search query string no Case-insensitive match on the contact’s name or phone number (longer text is cut to 100 characters).
page query integer no
pageSize query integer no
source query string: campaign, inbound, api, manual, widget, unknown no Call source. Unknown means the source was not recorded, never an inferred API call.
useCase query string no Exact use-case key from summary.useCases. Keys are use:<name>, campaign:<id>, line:<receiving-number>, or unlabelled.

Example request

Terminal window
curl -X GET "https://api.foan.ai/api/v1/voice/agents/{agentId}/results" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "items": [
      {
        "callId": "66f2a1c4e8b9d70012ab34cd",
        "startedAt": "2026-09-28T11:42:10.000Z",
        "durationSeconds": 96,
        "contactName": "Rahul Verma",
        "contactPhone": "+919876543210",
        "direction": "inbound",
        "outcomeKey": "booked",
        "outcomeLabel": "Booked",
        "captured": {
          "party_size": 4,
          "booking_time": "20:00"
        },
        "recordingUrl": "/api/v1/voice-sessions/66f2a1c4e8b9d70012ab34cd/recording",
        "resultSource": "flow",
        "flowPath": [
          "start",
          "ask_party",
          "book",
          "end_booked"
        ]
      },
      {
        "callId": "66f29e0be8b9d70012ab3399",
        "startedAt": "2026-09-28T10:05:44.000Z",
        "durationSeconds": 41,
        "contactName": null,
        "contactPhone": "+919812345678",
        "direction": "inbound",
        "outcomeKey": "transferred_to_human",
        "outcomeLabel": "Transferred to human (+91 98765 43210)",
        "captured": {
          "transferred_to": "+919876543210"
        },
        "recordingUrl": null,
        "resultSource": "flow",
        "flowPath": [
          "start",
          "handover"
        ]
      }
    ],
    "total": 128,
    "page": 1,
    "pageSize": 50
  }
}

Errors

Code When
400 from or to is not a date, from is not before to, outcome is not one the agent tracks, or page/pageSize is out of range.
401 Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation.
403 The key lacks the calls:read scope, or the agent belongs to another organisation.
404 Agent not found or deleted.
429 Rate limited

Download an agent’s call results as CSV

Section titled “Download an agent’s call results as CSV”

GET /voice/agents/{agentId}/results/export

Downloads every result row matching the same filters as GET /voice/agents/{agentId}/results as one CSV file (UTF-8 with a byte order mark, so spreadsheets open it correctly). Columns: Called on (date and time in the agent’s time zone), Caller, Phone, Source, Use case, Outcome, one column per detail the agent tracks, Minutes, Call status, Actions, Call score, Classification, Sentiment, They said, Original quote, Summary, Recording (full URL, needs recordings:read). Yes/no details read Yes or No. At most 20,000 calls per file: a bigger range is refused with 400 rather than cut short, so pick a shorter range or one outcome. The agent must belong to the API key’s organisation.

Scope: calls:read

Parameters

Name In Type Required Description
agentId path string yes Agent ID.
from query string no Start of the range, inclusive. A date (2026-09-01, read as midnight UTC) or an ISO-8601 timestamp. Defaults to 30 days before to.
to query string no End of the range, exclusive. A bare date includes that whole day (UTC). Defaults to now.
outcome query string no Only calls with this outcome key (one the agent tracks, or no_result).
search query string no Case-insensitive match on the contact’s name or phone number.
source query string: campaign, inbound, api, manual, widget, unknown no Call source. Unknown means the source was not recorded, never an inferred API call.
useCase query string no Exact use-case key from summary.useCases. Keys are use:<name>, campaign:<id>, line:<receiving-number>, or unlabelled.

Example request

Terminal window
curl -X GET "https://api.foan.ai/api/v1/voice/agents/{agentId}/results/export" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

Errors

Code When
400 Bad from/to, an outcome the agent does not track, or more than 20,000 matching calls.
401 Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation.
403 The key lacks the calls:read scope, or the agent belongs to another organisation.
404 Agent not found or deleted.
429 Rate limited

Get the default Results agent

Section titled “Get the default Results agent”

GET /voice/organisations/{organisationId}/results/default-agent

Returns the agent the Results page opens on: the agent with the most recent placed call, else the most recently updated agent, else null when the organisation has no agents. Deleted agents never count. Read only.

Scope: calls:read

Parameters

Name In Type Required Description
organisationId path string yes Your organisation ID (the API key’s organisation).

Example request

Terminal window
curl -X GET "https://api.foan.ai/api/v1/voice/organisations/{organisationId}/results/default-agent" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "agentId": "cmf3k2j9x0001abcd1234efgh"
  }
}

Errors

Code When
401 Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation.
403 The key lacks the calls:read scope, or organisationId is not the key’s organisation.
429 Rate limited