Skip to main content
GET
/
api
/
lists
List all lists
curl --request GET \
  --url https://app.puffle.ai/api/lists \
  --header 'Authorization: Bearer <token>'
{ "lists": [ { "id": "a1111111-1111-1111-1111-111111111111", "userId": "u1111111-1111-1111-1111-111111111111", "name": "Series A fintech founders", "enrichmentStatus": "idle", "createdAt": "2026-04-20T10:00:00Z", "updatedAt": "2026-04-22T09:30:00Z", "activeSearchId": null, "searchFilters": null, "rowCount": 42, "companyCount": 7 } ] }

​
Overview

Returns every list owned by the caller, newest first. Each entry includes exact rowCount and companyCount values computed via dedicated RPCs (not inline counts, which cap at 1000). The list is the top-level container for rows (people), companies, columns, and cells. Lists also hold an optional activeSearchId — set when a Trigger.dev lead-search task is bound to the list — and a searchFilters snapshot of the filter set used for that search.
This operation shares the URL path /api/lists with the create verb. See Create a list to create a new empty list seeded with built-in columns.

​
AI agent notes

No pagination. The list index returns every list in a single response — fewer than a few hundred entries in practice. If you need to page rows within a specific list, use GET /api/lists/{id}/rows instead.Exact counts. rowCount and companyCount come from dedicated RPCs, so they stay accurate even past the Supabase 1000-row inline-count ceiling.

Authorizations

​
Authorization
string
header
required

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

Response

Array of lists. Empty array is a valid response for new users.

​
lists
object[]
required

Every list owned by the caller, newest first. Each item includes rowCount and companyCount computed via dedicated RPCs (so counts are exact even for >1000-row lists).