MMetadata /docs
Docs/Tools/list_segments

list_segments

List the account's saved Insights (Spotlight) account-journey segments: {id, name, status, last_update_date}.

Read audiences

Returns data. Calling it changes nothing, so it is safe in an unattended loop.

What it does

List the account's saved Insights (Spotlight) account-journey segments: {id, name, status, last_update_date}.

Segments are shared with the SaaS UI (Spotlight > Journey), so a marketer may already have the one you need: check here BEFORE create_segment and reuse instead of creating a near duplicate.

`name` filters fuzzily (case-insensitive contains or a close match). An empty list means the account has no segments yet, not an error: create one with create_segment when the ask needs it. Creating needs an ACTIVE Insights (Spotlight) subscription on the account: create_segment checks it first and refuses with the subscription state when it is expired or missing. Relay that to the user instead of retrying; existing segments stay usable either way.

STATUS: READY can be used; PENDING is still extracting a CRM field (re-check later); FAILED cannot back an audience.

NEXT: get_segment_criteria(segment_id, lookback_window) to read a segment's filter and how many accounts it matches in a window; create_audience_from_segment to turn it into an audience; get_insights_report(criteria=...) to browse its accounts.

Arguments

ArgumentTypeNotes
name string Optional fuzzy search by name.
sort string Sort format: field,direction. Default: name,asc

Request

Request template, not a complete runnable example. Replace placeholders, empty objects, arrays, and zero values with valid account-specific inputs. Read required fields and nested constraints in the full schema. Confirm the account, connected channels, and referenced assets before calling a write tool.

curl
curl -s -X POST https://mcp-server.metadata.io/mcp \
  -H "Authorization: $METADATA_PAT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_segments","arguments":{}}}'

Response

Recorded 2026-09-05 from the production server, in 327 ms. Values that identify a customer or disclose money are replaced with typed placeholders; keys, types and nesting are exactly as returned.

recorded response
"[value redacted]"

Other audiences tools:

Browse the tool catalog · machine-readable index