Skip to main content

Pagination

List endpoints return paginated results with metadata about the total count and navigation.

Query Parameters​

All list endpoints accept these query parameters:

ParameterDefaultMaxDescription
limit50200Number of items per page
offset0—Starting position (0-indexed)

Example:

# Get 20 agents, starting at position 40
curl https://api.dialogbrain.com/api/v1/agents?limit=20&offset=40 \
  -H "X-API-Key: db_live_YOUR_KEY"

Response Envelopes​

The response format depends on the endpoint.

Conversations and Contacts​

Use items, total, limit, and offset:

curl https://api.dialogbrain.com/api/v1/conversations?limit=2 \
  -H "X-API-Key: db_live_YOUR_KEY"

Response:

{
  "items": [
    {
      "id": 1002,
      "title": "Booking request",
      "channel": "google_calendar",
      "kind": "calendar",
      "channel_ref": "google_calendar:example@group.v.calendar.google.com",
      "last_message_ts": "2026-08-22T10:30:00+00:00",
      "last_message_preview": "**Meeting scheduled**\nWhen: 2026-08-22 at 10:30am\n\nEvent confirmed",
      "unread_count": 4,
      "created_at": "2026-07-22T09:36:50.087471+00:00"
    },
    {
      "id": 1003,
      "title": "Support conversation",
      "channel": "whatsapp",
      "kind": "dm",
      "channel_ref": "whatsapp:15550100@s.whatsapp.net",
      "last_message_ts": "2026-08-22T02:50:31+00:00",
      "created_at": "2026-07-22T14:39:00.123456+00:00"
    }
  ],
  "total": 847,
  "limit": 2,
  "offset": 0
}

Agents​

Uses a different envelope format with agents, total, and count:

curl https://api.dialogbrain.com/api/v1/agents?limit=2 \
  -H "X-API-Key: db_live_YOUR_KEY"

Response:

{
  "agents": [
    {
      "id": 12,
      "name": "Voice Receptionist",
      "slug": "voice-receptionist",
      "description": "Answering machine for inbound WhatsApp and Telegram calls...",
      "text_engine": "agentic",
      "status": "active",
      "priority": 0,
      "trigger_count": 20,
      "knowledge_collection_count": 0,
      "is_template": false
    },
    {
      "id": 13,
      "name": "Support Bot",
      "slug": "support-bot",
      "description": null,
      "text_engine": "agentic",
      "status": "active",
      "priority": 100,
      "trigger_count": 0,
      "knowledge_collection_count": 1,
      "is_template": false
    }
  ],
  "total": 23,
  "count": 2
}

Field meanings:

  • total — Total agents in this workspace
  • count — Number of agents in this response

Contacts​

Contacts also use the items envelope:

curl https://api.dialogbrain.com/api/v1/contacts?limit=2 \
  -H "X-API-Key: db_live_YOUR_KEY"

Response:

{
  "items": [
    {
      "id": 1004,
      "display_name": "+1 555 0101",
      "canonical_name": null,
      "normalized_phone": null,
      "normalized_email": null,
      "avatar_url": null,
      "notes": null,
      "created_at": "2026-08-22T03:25:24.955713+00:00",
      "updated_at": "2026-08-22T03:25:24.955713+00:00"
    },
    {
      "id": 1005,
      "display_name": "Alice Example",
      "canonical_name": "alice example",
      "normalized_phone": null,
      "normalized_email": null,
      "avatar_url": null,
      "created_at": "2026-08-22T03:25:21.654321+00:00",
      "updated_at": "2026-08-22T03:25:21.654321+00:00"
    }
  ],
  "total": 15037,
  "limit": 2,
  "offset": 0
}

Iterating Through Pages​

With curl​

limit=50
offset=0
total=$(curl -s "https://api.dialogbrain.com/api/v1/conversations?limit=$limit&offset=$offset" \
  -H "X-API-Key: db_live_YOUR_KEY" | python3 -c "import json,sys; print(json.load(sys.stdin)['total'])")

while [ $offset -lt $total ]; do
  curl -s "https://api.dialogbrain.com/api/v1/conversations?limit=$limit&offset=$offset" \
    -H "X-API-Key: db_live_YOUR_KEY"
  offset=$((offset + limit))
done

With Python SDK​

from dialogbrain import DialogBrainClient

async with DialogBrainClient(api_key="db_live_YOUR_KEY") as client:
    # Automatically handles pagination
    conversations = await client.conversations.list()
    for conv in conversations["items"]:
        print(conv["title"])
    
    # Or get a specific page
    page = await client.conversations.list_page(limit=20, offset=0)
    print(f"Got {len(page['items'])} out of {page['total']}")

See also: Errors