ROroarkhq
Call

List calls

Changed on

Returns a paginated list of calls for the authenticated project. Pass agentId to keep calls for specific agents, or properties[agent_name][eq] when you only have the agent name. sortBy and sortDirection apply together with those filters.

get/v1/call

Request

  • Base URL
    https://api.roark.ai
  • URL
    https://api.roark.ai/v1/call
  • Auth
    HTTP bearer

Query parameters

limitinteger

Maximum number of calls to return (default: 20, max: 100)

Example:20
afterstring

Cursor for pagination - use the nextCursor value from a previous response

Example:eyJzb3J0VmFsdWUiOiIyMDI1LTAxLTE1VDEwOjAwOjAwLjAwMDAwMFoiLCJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9
sortBy'createdAt' | 'startedAt' | 'endedAt' | 'duration' | 'title' | 'status'

Field to sort by (default: createdAt)

Example:createdAt
sortDirection'asc' | 'desc'

Sort direction (default: desc)

Example:desc
status'RINGING' | 'IN_PROGRESS' | 'ENDED'

Filter by call status

Example:ENDED
searchTextstring

Search text to filter calls by title, summary, or transcript

Example:billing inquiry
agentIdstring

Calls that include any of these agents. One id, or several separated by commas, at most 100. A call with more than one agent matches when any of them is listed. An id that is not an agent on a call in this project matches nothing. Combines with the other filters, including sortBy and sortDirection.

Example:550e8400-e29b-41d4-a716-446655440000,660e8400-e29b-41d4-a716-446655440001
simulationRunPlanJobIdstring uuid

Filter by simulation run plan job ID to get all calls from a specific simulation batch

Example:550e8400-e29b-41d4-a716-446655440000
simulationRunPlanJobIdsstring

Calls from any of these simulation runs (run plan job ids), comma-separated, at most 100

Example:550e8400-e29b-41d4-a716-446655440000,660e8400-e29b-41d4-a716-446655440001
simulationRunPlanIdsstring

Calls from every run of any of these run plans, comma-separated, at most 100

Example:770e8400-e29b-41d4-a716-446655440002
countedInResults'true' | 'false'

true: only simulated calls their run's results count (not invalidated, for example because the agent never spoke). false: only the simulated calls the results leave out, each invalidated. Live calls, and calls removed from their run, match neither.

Example:true
excludeHiddenRuns'true' | 'false'

true: leave out calls from runs hidden from the runs list. Live calls stay in. false is the same as leaving it out.

Example:true
propertiesobject

Filter on properties, one entry per property name. properties[<name>][exists]=true keeps calls that have the property set (whatever the value), properties[<name>][exists]=false keeps calls missing it (never sent, sent as null, or removed). properties[<name>][eq]=<value> keeps calls whose value equals it, ignoring case. agent_name and agent_id are built in and read the agents linked to the call, not a stored snapshot: agent_name matches an agent name, agent_id matches an agent id (a UUID). A call with several agents matches when any of them does. A custom property the project has never stored matches no calls under eq. Names match the way properties are stored, so planTier and plan_tier are one property, and agentName is agent_name. At most 20 properties. A name taken by a built-in call filter, such as status, is rejected with 400. One operator per property.

{
  "plan_tier": {
    "exists": false
  },
  "agent_name": {
    "eq": "Billing Bot"
  }
}

Response

List of calls

Example response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "projectId": "660e8400-e29b-41d4-a716-446655440001",
      "title": "Customer support inquiry",
      "summary": "Customer inquired about billing and payment options",
      "status": "ENDED",
      "callDirection": "INBOUND",
      "startedAt": "2024-01-15T10:00:00Z",
      "endedAt": "2024-01-15T10:30:00Z",
      "durationMs": 1800000,
      "endedStatus": "AGENT_ENDED_CALL",
      "recordingUrl": "https://s3.amazonaws.com/bucket/recording.mp3?...",
      "recordingUrlAccess": "AVAILABLE",
      "simulationJobId": "880e8400-e29b-41d4-a716-446655440003",
      "supersededByCallId": "990e8400-e29b-41d4-a716-446655440004",
      "externalId": "session-abc-123",
      "agents": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "endpoint": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "environment": "Production",
            "phoneNumberE164": "+1234567890"
          }
        }
      ],
      "customers": [
        {
          "phoneNumberE164": "+1234567891",
          "label": "customer-01"
        }
      ],
      "createdAt": "2024-01-15T10:31:00Z",
      "updatedAt": "2024-01-15T10:31:00Z",
      "properties": {
        "ticketId": "TCK-123",
        "department": "sales"
      },
      "policyIds": [
        "550e8400-e29b-41d4-a716-446655440000"
      ]
    }
  ]
}

Changes