Export bot conversations (reporting)

Retrieve bot conversations in a reporting-friendly format with cursor pagination.

GET /api/v1/reporting/tenants/{tenantId}/botconv

List bot conversations (reporting format)

cURL

curl --request GET \
  --url https://platform.crescendo.ai/api/v1/reporting/tenants/{tenantId}/botconv \
  --header 'Authorization: Bearer <token>'

200

{
  "total": 123,
  "cursor": {
    "next": "<string>"
  },
  "data": [
    {
      "ID": "<string>",
      "TenantID": "<string>",
      "BotID": "<string>",
      "BotName": "<string>",
      "Datetime": 123,
      "EndDatetime": 123,
      "DatetimeUTC": "2023-11-07T05:31:56Z",
      "EndDatetimeUTC": "2023-11-07T05:31:56Z",
      "Duration": 123,
      "Escalated": true,
      "CSat": 123,
      "AgentName": "<string>",
      "AgentId": "<string>",
      "AgentEmail": "<string>",
      "Category": "<string>",
      "Subcategory": "<string>",
      "Tertiary": "<string>",
      "RemoteIp": "<string>",
      "Referrer": "<string>",
      "Media": "<string>",
      "Summary": "<string>",
      "Handoff Reason": "<string>",
      "Input": "<string>",
      "Contact Name": "<string>",
      "Contact Email": "<string>",
      "Contact Phone": "<string>"
    }
  ]
}

This endpoint returns bot conversations as reporting rows (no message content), suitable for exporting large time ranges.

Date range filtering

You can specify a time range using either:

• range=last_day|last_week|last_month, or
• from / to (ISO 8601 or epoch millis)

If you do not supply a range, the default is range=last_day.

Pagination (cursor)

Results are paginated using an opaque cursor:

• Use limit to control page size (default 1000, max 5000)
• Use cursor to fetch the next page (from cursor.next)
• When you supply cursor, do not also supply range, from, or to

Example: first page

export CRESCENDO_TENANT_ID="tenant-alpha"
export CRESCENDO_API_KEY="YOUR_API_KEY"

curl -sS \
  -H "Authorization: Bearer $CRESCENDO_API_KEY" \
  "https://platform.crescendo.ai/api/v1/reporting/tenants/$CRESCENDO_TENANT_ID/botconv?range=last_week&limit=1000"

Example: next page

export CURSOR="PASTE_cursor.next_HERE"

curl -sS -G \
  -H "Authorization: Bearer $CRESCENDO_API_KEY" \
  --data-urlencode "cursor=$CURSOR" \
  "https://platform.crescendo.ai/api/v1/reporting/tenants/$CRESCENDO_TENANT_ID/botconv"

Example: fetch all pages (Node.js)

const baseUrl = 'https://platform.crescendo.ai';

async function fetchAllBotconv({ tenantId, apiKey, limit = 1000, range = 'last_week' }) {
  const allRows = [];

  // First request can use range/from/to
  let cursor = null;
  let first = true;

  while (true) {
    const url = new URL(`${baseUrl}/api/v1/reporting/tenants/${tenantId}/botconv`);

    if (first) {
      url.searchParams.set('range', range);
      url.searchParams.set('limit', String(limit));
      first = false;
    } else {
      url.searchParams.set('cursor', cursor);
      url.searchParams.set('limit', String(limit));
    }

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);

    const body = await res.json();
    allRows.push(...(body.data ?? []));

    cursor = body?.cursor?.next;
    if (!cursor) break;
  }

  return allRows;
}

Authorizations

bearerAuthbearerTokenQuery

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

tenantId · string · required

Tenant identifier.

Query Parameters

limit · integer<int32>

Max results per page. Default 1000, max 5000.

Required range: 1 <= x <= 5000

cursor · string

Opaque cursor returned in cursor.next. When provided, do not also supply range, from, or to.

range · enum<string>

Convenience range selector. If omitted and from is omitted, defaults to last_day.

Available options: last_day, last_week, last_month

from · integer<int64> string<date-time>

Range start. Accepts an ISO 8601 timestamp or epoch milliseconds. Epoch milliseconds.

to · integer<int64> string<date-time>

Range end. Accepts an ISO 8601 timestamp or epoch milliseconds. Defaults to now. Epoch milliseconds.

Response

200

application/json

OK

total · integer<int64> · required

cursor · object · required

Show child attributes

data · object[] · required

Show child attributes