GET /v1/shortlists

List shortlists

Access

Authenticated

shortlist:read

Cost

Free

Rate limit

60 / minute per account

Quota

None

Your account shortlists with derived member counts. Excludes archived unless archived=true.

Query parameters

limit integer default: 25

min 1, max 250
offset integer | null default: 0

min 0, max 100000
archived string

truefalse
pinned string

truefalse

Responses

200 The shortlists
- rows array of Shortlist required
  
  This page of shortlists.
  - id string required
    
    The shortlist id.
  - name string required
    
    The list name.
  - kind string required
    
    What kind of list this is: `project` for a list linked to a project you can read, `freestanding` for every other list. Seeing `project` needs project:read: without it a list linked to a project reads `freestanding` like any other. An API key or a connected AI client does not hold project:read.
    
    freestandingprojectpipeline
  - description string | null required
    
    Free-text description. Null when none.
  - ownerId string | null required
    
    The member or API key that owns the list, as an actor id. Null when it has no individual owner.
  - pinned boolean required
    
    Whether the list is pinned for quick access.
  - archivedAt string | null required
    
    When the list was archived, as an ISO 8601 instant. An archived list is hidden from the default listing but keeps its members and sequences. Null while active.
  - createdAt string required
    
    When the list was created, as an ISO 8601 instant.
  - agentId string | null required
    
    The managed agent that owns this list, when one does. The list is yours either way; this only says who keeps it up to date.
  - stats object required
    
    Member and sequence counts for this list.
    
    members integer required
    
    How many contacts are on this list.
    
    sequences integer required
    
    How many outreach sequences are attached to it.
- total integer required
  
  How many shortlists match the filters in total, not just on this page.
401 No or invalid credential
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_errorbuild_failed
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at how to restore access).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.
403 Missing shortlist:read
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_errorbuild_failed
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at how to restore access).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.
429 A rate limit or a usage quota is exhausted. Back off and retry; the `x-quota-*` response headers report the remaining allowance.
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_errorbuild_failed
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at how to restore access).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.