Graine AI
API referenceCalls

List executions

List this organization's call executions, newest first.

List this organization's call executions, newest first.

Unlike the older dashboard API, in-flight calls are visible by default. Omitting status returns everything — scheduled, queued, ringing, in-progress and terminal alike — so a partner polling for a call they just placed can actually see it. Pass status only to narrow the result.

A call that has not dialled yet is listed too, at status: "scheduled" with the scheduled_at it will ring at. That covers both an explicit scheduled_at and a call the agent's calling guard moved into its window, so ?status=scheduled is the upcoming list and the calls in it can be cancelled with POST /v2/calls/{execution_id}/stop.

status accepts a comma-separated list and tolerates both spellings of the values that have two (no-answer/no_answer, in-progress/in_progress, cancelled/canceled). It also accepts voicemail, which is not a status at all: a voicemail pickup is stored as no-answer plus a flag, so that filter matches the flag.

Returns the standard list envelope: {"data": [...], "pagination": {...}}.

Rate limit: 600 requests per minute per organization (bucket executions.list). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

GET
/v2/calls
/v2/calls?agent_id=6c6f4cc3-f56c-479d-8422-7f76694daa29&batch_id=5315887d-38a1-45c0-876c-d733f83181b9&campaign_id=31ff3ea9-8bb5-433f-868f-286ac3c31328&status=completed&direction=outbound&from_date=2026-08-01T00%3A00%3A00%2B05%3A30&to_date=2026-08-27T00%3A00%3A00%2B05%3A30&phone_number=%2B919812345678&include_transcript=false&page=1&page_size=20

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.

In: header

Query Parameters

agent_idAgent Id

Only calls placed by this agent.

batch_idBatch Id

Only calls placed by this batch.

campaign_idCampaign Id

Only calls in this campaign.

statusStatus

Comma-separated statuses, e.g. completed,no-answer. Also accepts the pseudo-status 'voicemail', which matches calls answered by a voicemail box regardless of their stored status. Omit to see every call, in-flight ones included.

directionDirection

inbound | outbound

from_dateFrom Date

Only calls created at or after this ISO-8601 timestamp.

to_dateTo Date

Only calls created at or before this ISO-8601 timestamp.

phone_numberPhone Number

Exact E.164 match on the recipient number.

include_transcriptInclude Transcript

Include the full transcript on every row. Slower and much larger.

Default: false

organization_idOrganization Id

Optional. Must equal your key's organization.

pagePage

1-indexed page number (max 10000 — narrow the window instead)

Default: 1Minimum: 1Maximum: 10000

page_sizePage Size

Items per page (max 100)

Default: 20Minimum: 1Maximum: 100

Response Body

200

A page of executions, newest first.

data
Required
Data

This page of executions, newest first.

pagination
Required
Pagination

Where this page sits in the result set.

400

1000 — malformed or contradictory input. 1002 — a required parameter is missing.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

401

1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented instead of an API key.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

403

1102 — the key is valid but lacks the scope this endpoint requires, or names another organization. GET /v2/scopes reports what a key holds.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

422

1001 — the body or query failed validation; the message names the first offending field.

error
Required
integer

Stable integer code from the error table. Branch on this, not on the message.

message
Required
string

One human-readable sentence. Wording may change; the code will not.

429

1300 — the per-organization request rate or concurrent-call limit was reached. Carries Retry-After.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

503

1501 — a service this endpoint depends on is unreachable or returned a 5xx.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

curl -X GET "https://api.graine.ai/v2/calls?agent_id=6c6f4cc3-f56c-479d-8422-7f76694daa29&batch_id=5315887d-38a1-45c0-876c-d733f83181b9&campaign_id=31ff3ea9-8bb5-433f-868f-286ac3c31328&status=completed&direction=outbound&from_date=2026-08-01T00%3A00%3A00%2B05%3A30&to_date=2026-08-27T00%3A00%3A00%2B05%3A30&phone_number=%2B919812345678&include_transcript=false&organization_id=string&page=1&page_size=20" \
  -H "Authorization: Bearer <token>"

A page of executions, newest first.

{
  "data": [
    {
      "execution_id": "dbcffa37-92a1-4ae7-9814-71ca7b8ab3d3",
      "status": "completed",
      "is_terminal": true,
      "direction": "outbound",
      "agent_id": "6c6f4cc3-f56c-479d-8422-7f76694daa29",
      "batch_id": "7d1f0a52-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
      "campaign_id": "31ff3ea9-8bb5-433f-868f-286ac3c31328",
      "contact_id": "c41f7e02-9b8a-4d51-b0c7-6f2a1e3d4c55",
      "parent_execution_id": "9b2c1d84-77e3-4a10-8f5b-2c6d9e0a1b33",
      "retry_count": 0,
      "to_number": "+919812345678",
      "from_number": "+917971442184",
      "provider": "custom",
      "duration_seconds": 209,
      "answered_by_voicemail": false,
      "hangup_by": "Caller",
      "hangup_reason": "User disconnected the call",
      "recording_url": "https://storage.graine.ai/2026/08/26/0d76fa8c-ea49-4d78-9e5b-1a15ab7b3ac2.mp3",
      "cost": {
        "total": 0.134068,
        "currency": "USD",
        "breakdown": {
          "llm": 0.020814,
          "network": 0,
          "platform": 0.01,
          "synthesizer": 0.052034,
          "telephony": 0.02,
          "transcriber": 0.03122
        }
      },
      "summary": "Dealer was unaware of the campaign; the cashback process was explained.",
      "sentiment": "neutral",
      "extracted_data": {
        "call_outcome": "already_knew_no_doubts",
        "follow_up": false,
        "callback_time_requested": ""
      },
      "custom_analytics": [
        {
          "name": "Custom Analytics",
          "required_keys": [
            "call_outcome"
          ]
        }
      ],
      "variables": {
        "callee_name": "Raju",
        "agent_name": "Priya Plumber Activation Agent"
      },
      "error": {
        "message": "The recipient's carrier rejected the call."
      },
      "scheduled_at": "2026-08-27T09:30:00.000Z",
      "created_at": "2026-08-26T12:19:54.580Z",
      "updated_at": "2026-08-26T12:25:01.543Z",
      "completed_at": "2026-08-26T12:23:35.194Z",
      "transcript": [
        {
          "role": "assistant",
          "content": "Namaste, main Kavya bol rahi hoon."
        },
        {
          "role": "user",
          "content": "Haan boliye."
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 137,
    "total_pages": 7,
    "has_more": true
  }
}

Previous

Fetch one execution GET

Next

Stop or cancel a call POST