Poll for calls

GET /api/v1/conversations returns finished calls across every agent. Filter on since to fetch only what changed since your last poll.

The polling pattern

First poll

Call the endpoint with since=0 to retrieve all calls, then save the largest created_at in the response as your cursor.

curl

curl "https://api.formbharo.artpark.ai/api/v1/conversations?since=0" \
  -H "Authorization: Bearer <api-key>"

Later polls

Pass the saved cursor as since=<last_created_at>. Save the new largest created_at each time.

Repeat

Poll at most a few times per minute.

Things to know

since is inclusive, so the call at the boundary comes back in the next poll.
created_at is the last-write time, not the call start time. Editing an answer on an old call moves it into the current window. Match on conversation_id and update the existing row instead of inserting a new one.

Example request

curl -G "https://api.formbharo.artpark.ai/api/v1/conversations" \
  -H "Authorization: Bearer <api-key>" \
  --data-urlencode "since=0" \
  --data-urlencode "status=complete" \
  --data-urlencode "limit=50"

import requests

BASE_URL = "https://api.formbharo.artpark.ai"
HEADERS = {"Authorization": "Bearer <api-key>"}

def poll_conversations(since: int = 0) -> list[dict]:
    params = {
        "since": since,
        "status": "complete",
        "limit": 50,
    }

    all_conversations = []
    cursor = None

    while True:
        if cursor:
            params["cursor"] = cursor

        response = requests.get(
            f"{BASE_URL}/api/v1/conversations",
            headers=HEADERS,
            params=params,
        )
        response.raise_for_status()
        data = response.json()

        all_conversations.extend(data.get("data", []))

        cursor = data.get("next_cursor")
        if not cursor:
            break

    return all_conversations

results = poll_conversations(since=0)

if results:
    last_created_at = max(r["created_at"] for r in results)
    print(f"Next poll: since={last_created_at}")

Query parameters

Parameter	Description
`agent_id`	Only conversations for one agent
`workspace_id`	Only conversations for one workspace
`status`	`in_progress`, `complete`, `screened_out`, or `failed`
`source`	The source that started the call
`since`	Unix timestamp, inclusive: `created_at >= since`
`until`	Unix timestamp, inclusive: `created_at <= until`
`limit`	Rows per page, `1` to `200`. Defaults to `50`
`cursor`	The `next_cursor` from the previous response

Fetching transcripts

Transcripts are not in the cross-agent list. Fetch them one call at a time.

curl

curl "https://api.formbharo.artpark.ai/api/v1/agents/AGENT_ID/conversations/CONVERSATION_ID/transcript" \
  -H "Authorization: Bearer <api-key>"

A call with no recorded speech returns 404 with { "error": "Transcript not found" }. Treat it as an empty transcript, not a failure.

Get Started

Guides

Reference

The polling pattern

Things to know

Example request

Query parameters

Fetching transcripts

​The polling pattern

​Things to know

​Example request

​Query parameters

​Fetching transcripts

The polling pattern

Things to know

Example request

Query parameters

Fetching transcripts