Topolo Docs Topolo Platform
Open workspace

List prospect lists

Discover active prospect lists and their current active-contact counts.

Outcome

Discover active prospect lists and their current active-contact counts.

Before you start

  • Verify the environment, credential, authorized organization and the published action permission workspace:read.
  • Discover an accessible Engage workspace and bind resourceType=workspace and its resourceId separately from action input. Fixture identifiers grant no access.

Discover the target

  • Select the authorized Engage workspace. Supply an empty input object; this action has no pagination or search parameters.
topolo whoami --json
topolo actions get app_topolo_engage.lists.list --json
topolo workspaces list topolo-engage --json

Input fields

This action accepts an empty input object ({}). Resource context is supplied separately.

Validate, plan and execute

Set ENGAGE_WORKSPACE_ID to the identifier of your selected workspace. Prepare payload.json from the current input schema and discovered identifiers. Use the same payload for validation, planning and execution.

: "${ENGAGE_WORKSPACE_ID:?Set ENGAGE_WORKSPACE_ID to your selected workspace identifier}"
topolo actions validate app_topolo_engage.lists.list --data @payload.json --json
topolo actions plan app_topolo_engage.lists.list --resource-type workspace --resource-id "$ENGAGE_WORKSPACE_ID" --data @payload.json --json

Execute the unchanged validated read in the selected workspace.

: "${ENGAGE_WORKSPACE_ID:?Set ENGAGE_WORKSPACE_ID to your selected workspace identifier}"
topolo actions call app_topolo_engage.lists.list --resource-type workspace --resource-id "$ENGAGE_WORKSPACE_ID" --data @payload.json --json

For MCP, use topolo_get_action, topolo_validate_action, topolo_plan_action and topolo_call_action. Pass the selected resource context separately; confirm:true is required for mutations.

Worked requests and responses

Captured lists.list · HTTP 200

Action input

{}

Actual local response

{
  "lists": []
}

Source test: audience routes > lists > keeps lists and memberships inside their workspace. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured lists.list · HTTP 200

Action input

{}

Actual local response

{
  "lists": [
    {
      "id": "list_1",
      "name": "Founders",
      "description": null,
      "memberCount": 0,
      "createdAt": "2026-10-01T00:00:00.000Z",
      "updatedAt": "2026-10-01T00:00:00.000Z",
      "archivedAt": null
    }
  ]
}

Source test: audience routes > lists > creates, lists, edits and archives a list. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Effects and response meaning

  • Returns all active lists in lists[], ordered by createdAt descending then id descending. Archived lists are omitted; no cursor is returned.
  • memberCount counts memberships of active contacts only. It is not a total of all historical membership rows. Listing does not enroll contacts or send outreach.

Verify the result

  • Retain lists[].id for lists.get. Use contacts.list with listId and follow nextCursor to inspect active members.
  • An empty array means no active lists were found in this workspace; it does not prove there are no archived lists.

Recover

Retry this read after a transient failure with the same verified workspace and validated input. Rediscover missing identifiers within that workspace; never create or modify a record to make a read succeed.

Refused responses

Captured lists.list · HTTP 503

Action input

{}

Actual local response

{
  "error": {
    "code": "address_hashing_unconfigured",
    "message": "Contact storage is unavailable: the address hashing secret is not configured."
  }
}

Source test: audience routes > fails closed with 503 when the address hashing secret is missing. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Error recovery

  • HTTP 403 permission_denied: Stop and inspect the permission required by this action in the current credential. Do not broaden permissions or switch organization automatically.
  • HTTP 422 invalid_action_input: Correct the request against the current input schema and validate it again before planning.
  • HTTP 503 address_hashing_unconfigured: Stop and report the missing address-hashing configuration to the application operator. This read cannot provision it; do not switch context or modify credentials to bypass the refusal.

Evidence and limits

  • contracts/audience.mjs

  • contracts/audience-filter.mjs

  • apps/api/src/audience/audience-routes.ts

  • apps/api/src/audience/contacts-handlers.ts

  • apps/api/src/audience/contact-search.ts

  • apps/api/src/audience/contacts-repository.ts

  • apps/api/src/audience/lists-handlers.ts

  • apps/api/src/audience/lists-repository.ts

  • apps/api/src/audience/filter-source.ts

  • apps/api/test/audience-routes.test.ts

  • apps/api/test/segments-routes.test.ts

  • Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

  • Widget/bootstrap use actual app handler but mocked worker runtime and app identity.

  • No gateway execution, live permissions, external delivery or deployed proof.

The examples are local route captures with synthetic context and simulated providers. They do not prove live authorization, CLI/MCP gateway execution, production state or delivery.