Agent API/Transcripts

List Transcripts

Returns a paginated list of conversation transcripts for your agent — metadata only (no message history). Use the ?month= or start/end date parameters to narrow by period, and ?channel= or ?status= to filter further. To retrieve the full message history for a conversation, use the Get Transcript endpoint.

GET

https://agent.askhandle.com/api/v1/public/transcripts

Requires X-API-Key — Your agent API key (pk_live_...)

Request

Headers

X-API-Key

stringrequired

Your agent API key (pk_live_...)

Query Parameters

month

string

Calendar month in YYYY-MM format (e.g. "2026-03")

start

string

Start date ISO string (requires end)

end

string

End date ISO string (requires start)

channel

string

Filter by channel: widget | api | portal | web | whatsapp

status

string

Filter by status: active | completed

limit

number

Max results per page (1–100, default 20)

offset

number

Pagination offset (default 0)

Response

Success 200

JSON

{
  "transcripts": [
    {
      "id": "cm1abc123def456",
      "sender": "conv_abc123",
      "channel": "widget",
      "status": "completed",
      "messageCount": 12,
      "startedAt": "2026-03-10T14:22:00.000Z",
      "endedAt": "2026-03-10T14:35:00.000Z",
      "endedReason": "exit_node",
      "needsEscalation": false,
      "hasLead": true
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Errors

401

API key missing or invalid

Error

{
  "error": "Invalid API key."
}

Code examples

const res = await fetch(
  'https://agent.askhandle.com/api/v1/public/transcripts?month=2026-03&limit=20',
  { headers: { 'X-API-Key': 'pk_live_your_api_key_here' } }
);
const { transcripts, pagination } = await res.json();
console.log('Loaded:', transcripts.length, '— has more:', pagination.hasMore);
transcripts.forEach(t => {
  console.log(t.id, t.channel, t.messageCount + ' messages');
});

Request

Headers

X-API-Key

stringrequired

Your agent API key (pk_live_...)

Query Parameters

month

string

Calendar month in YYYY-MM format (e.g. "2026-03")

start

string

Start date ISO string (requires end)

end

string

End date ISO string (requires start)

channel

string

Filter by channel: widget | api | portal | web | whatsapp

status

string

Filter by status: active | completed

limit

number

Max results per page (1–100, default 20)

offset

number

Pagination offset (default 0)

Response

Success 200

JSON

{
  "transcripts": [
    {
      "id": "cm1abc123def456",
      "sender": "conv_abc123",
      "channel": "widget",
      "status": "completed",
      "messageCount": 12,
      "startedAt": "2026-03-10T14:22:00.000Z",
      "endedAt": "2026-03-10T14:35:00.000Z",
      "endedReason": "exit_node",
      "needsEscalation": false,
      "hasLead": true
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Errors

401

API key missing or invalid

Error

{
  "error": "Invalid API key."
}

const res = await fetch( 'https://agent.askhandle.com/api/v1/public/transcripts?month=2026-03&limit=20', { headers: { 'X-API-Key': 'pk_live_your_api_key_here' } } ); const { transcripts, pagination } = await res.json(); console.log('Loaded:', transcripts.length, '— has more:', pagination.hasMore); transcripts.forEach(t => { console.log(t.id, t.channel, t.messageCount + ' messages'); });