List All Lists

Returns a paginated list of the lists in your workspace, most recent first. Optionally filter by type. The total is in meta.pagination.

Archived lists are left out by default — pass include_archived=true to get them alongside the active ones, and read archived_at to tell them apart. Deleted lists never appear here, whatever you pass.

List all lists

GET/api/v2/lists

Query parameters

Parameter	Type	Description
page	integer	Page number, starting at 1. Defaults to 1.
page_size	integer	Items per page. Defaults to 25, max 100.
type	enum	Optional filter — one of `competitor`, `partner`, `customer`, `prospect`, `influencer`, `champion`, `employee`.
include_archived	boolean	Pass `true` to include archived lists. Defaults to `false`.
persona_id	integer	Optional. Returns the lists that belong to this persona, plus every list that belongs to no persona. Omit to get every list in the workspace. This id is specific to your environment.
response_format	enum	`concise`, `normalized` (default), or `detailed`. `concise` returns `id`, `kind`, `type` and `name` only; `normalized` and `detailed` are identical and add `description`, the counts, `tier`, the list defaults and `archived_at`.

Example request

curl "https://api.getsillage.com/api/v2/lists?page=1&page_size=25" \
  -H "Authorization: Bearer $SILLAGE_API_KEY"

Example response

{
  "data": [
    {
      "id": 128,
      "kind": "company",
      "type": "competitor",
      "name": "Key competitors",
      "description": "Companies we track for competitive signals",
      "tier": null,
      "default_tracking_status": "followed",
      "default_signal_bucket": "bucket_1",
      "member_count": 12,
      "bound_agent_count": 1,
      "archived_at": null,
      "persona_ids": []
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 25,
      "page_count": 1,
      "total": 1
    }
  }
}

Response fields

Field	Type	Description
data[].id	integer	Identifier of the list. Specific to your environment.
data[].kind	string	`company` or `profile`, derived from `type`.
data[].type	string	The immutable list type.
data[].name	string	Display name.
data[].description	string	Description, or `null`.
data[].tier	integer	`1`, `2` or `3` on `customer` and `prospect` lists; `null` on every other type, and `null` on a list that has never been given a tier. Read-only.
data[].default_tracking_status	string	`followed` or `unfollowed` — applies to every member that has no override of its own.
data[].default_signal_bucket	string	`bucket_1`, `bucket_2` or `bucket_3` — applies to every member that has no override. Read-only.
data[].member_count	integer	Number of members.
data[].bound_agent_count	integer	Number of agents bound to this list.
data[].persona_ids	integer[]	The personas this list belongs to. An empty array means the list applies to every persona.

Errors

Status	Description
400	Invalid request.
401	The API key is missing or invalid.
422	Invalid query parameters, or `persona_id` does not belong to your workspace.
429	Too many requests.
500	An unexpected server error occurred.