Skip to main content
GET
/
api
/
lists
/
{id}
Get a list
curl --request GET \
  --url https://app.puffle.ai/api/lists/{id} \
  --header 'Authorization: Bearer <token>'
{ "sheet": { "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 }, "rows": [ { "id": "r1111111-1111-1111-1111-111111111111", "listId": "a1111111-1111-1111-1111-111111111111", "linkedinUrl": "https://linkedin.com/in/jane-doe", "profileData": { "firstName": "Jane", "lastName": "Doe", "fullName": "Jane Doe", "currentRole": "Founder & CEO", "currentCompany": "Acme Capital" }, "source": "sales_nav", "addedAt": "2026-04-20T10:05:00Z", "companyRowId": null, "companyDomain": "acme.com" } ], "columns": [ { "id": "c1111111-1111-1111-1111-111111111111", "listId": "a1111111-1111-1111-1111-111111111111", "name": "Name", "prompt": "", "responseType": "text", "source": "profile", "subject": "person", "isFilter": false, "position": 0, "schema": { "type": "text" }, "enrichmentType": null, "config": null, "createdAt": "2026-04-20T10:00:00Z", "isPreview": false, "category": "built-in", "builtInKey": "name" } ], "cells": [ { "id": "e1111111-1111-1111-1111-111111111111", "columnId": "c1111111-1111-1111-1111-111111111111", "rowId": "r1111111-1111-1111-1111-111111111111", "value": "Jane Doe", "status": "completed", "reasoning": null, "error": null, "createdAt": "2026-04-20T10:05:00Z", "updatedAt": "2026-04-20T10:05:00Z" } ] }

​
Overview

Returns the list summary plus rows, columns, and cells for the requested segment (default people). Pass ?segment=companies to read the company-side view. The response returns everything needed to render the spreadsheet view in one call — no separate paginated fetches required. For larger lists, prefer GET /api/lists/{id}/rows which pages and returns row-level cells.
This operation shares the URL path /api/lists/{id} with other verbs. See Update a list to rename, or Delete a list to cascade-delete the list and all its rows, columns, and cells.

​
AI agent notes

Segment parameter. Lists carry two parallel dimensions — people (rows, list_cells) and companies (list_company_rows, list_company_cells). Passing ?segment=companies switches the response to the company side. Column shapes differ per segment: subject: "person" columns attach to rows, subject: "company" columns attach to company rows.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
string<uuid>
required

List UUID.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Query Parameters

​
segment
enum<string>

Which segment of the list to return. Defaults to people.

Available options:
people,
companies

Response

List with its rows, columns, and cells. rows and cells shapes change based on segment.

​
sheet
object
required

Canonical List entity in camelCase. Returned by every list endpoint under a sheet key (historical — rows and columns together formed a spreadsheet-like sheet).

​
rows
object[]
required
​
columns
object[]
required
​
cells
object[]
required