Back to Home
Dashboard

List Leads

Retrieve a chatbot's leads with filtering and pagination

GET
5 min read

Endpoint

Lists the leads of one chatbot in your workspace

GET https://pollybot.app/api/v1/chatbots/{chatbotId}/leads

Required Headers

Authorization: Bearer sk-workspace_your_api_key_here

Path Parameters

chatbotId

The unique identifier of the chatbot (required). Must belong to the workspace of the API key.

string

Query Parameters

All query parameters are optional

ParameterTypeDefaultDescription
pageinteger1Page number. Values below 1 are clamped to 1.
limitinteger50Leads per page. Clamped to the range 1–100.
statusstring—Filter by lead status: NEW, CONTACTED, QUALIFIED, NEGOTIATING, CONVERTED, LOST, UNRESPONSIVE.
prioritystring—Filter by priority: LOW, MEDIUM, HIGH, URGENT.
searchstring—Case-insensitive substring match against name, email, and company.
sortBystringcreatedAtLead field to sort by.
sortOrderstringdescSort direction: asc or desc.

Example Requests

List leads with and without filters

Basic request

curl "https://pollybot.app/api/v1/chatbots/cmqjwkljc00892znge0tk4c37/leads?page=1&limit=50" \
  -H "Authorization: Bearer sk-workspace_your_api_key_here"

Filtered and sorted

curl "https://pollybot.app/api/v1/chatbots/cmqjwkljc00892znge0tk4c37/leads?status=NEW&priority=HIGH&search=acme&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer sk-workspace_your_api_key_here"

Success Response

200 OK — leads, pagination, and the chatbot they belong to

{
  "success": true,
  "data": {
    "leads": [
      {
        "id": "cmf8x2k3j0001abcdef123456",
        "chatbotId": "cmqjwkljc00892znge0tk4c37",
        "conversationId": "cmf8x1p9a0000abcdef123456",
        "name": "Jane Cooper",
        "email": "jane@acme.com",
        "phone": "+14155550132",
        "company": "Acme Inc",
        "message": "Interested in the Pro plan",
        "source": "chat_widget",
        "status": "NEW",
        "priority": "MEDIUM",
        "assignedAgentId": null,
        "notes": null,
        "tags": ["pricing"],
        "customFields": null,
        "followUpDate": null,
        "lastContactAt": null,
        "convertedAt": null,
        "createdAt": "2026-08-15T09:24:11.000Z",
        "updatedAt": "2026-08-15T09:24:11.000Z",
        "discord": null,
        "preferredMethod": "email",
        "urgency": "low",
        "chatbots": {
          "id": "cmqjwkljc00892znge0tk4c37",
          "name": "Support Bot"
        }
      }
    ],
    "pagination": {
      "current": 1,
      "total": 1,
      "count": 1,
      "totalLeads": 1,
      "hasNext": false,
      "hasPrev": false,
      "limit": 50
    },
    "chatbot": {
      "id": "cmqjwkljc00892znge0tk4c37",
      "name": "Support Bot"
    }
  }
}

pagination.current is the requested page, pagination.total is the total number of pages, pagination.count is the number of leads on this page, and pagination.totalLeads is the number of leads matching the query. Use hasNext / hasPrev to page through results.

Each lead also includes a chatbots object with the owning chatbot's id and name.

Rate Limit Headers

Every successful response includes your current rate limit state (1000 requests per hour per API key):

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1774521600

Error Responses

All errors return success: false with an error code

StatusCodeWhen
401
AUTHENTICATION_FAILEDMissing, malformed, invalid, or inactive API key.
404
CHATBOT_NOT_FOUNDThe chatbot does not exist or does not belong to your workspace.
429
RATE_LIMIT_EXCEEDEDMore than 1000 requests in an hour with this API key.
500
INTERNAL_ERRORUnexpected server error.

401 Unauthorized

{
  "success": false,
  "error": "Invalid or inactive API key",
  "code": "AUTHENTICATION_FAILED",
  "timestamp": "2026-08-19T10:30:00.000Z"
}

404 Not Found

{
  "success": false,
  "error": "Chatbot not found or access denied",
  "code": "CHATBOT_NOT_FOUND"
}
Lead API OverviewGet Lead