---
title: "List Persona Groups"
method: GET
path: "/v1/personas/groups"
tags: ["personas"]
---

# List Persona Groups

`GET /v1/personas/groups`

## Request

- Base URL: `https://api.evidenso.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.evidenso.com/v1/personas/groups`
- Auth: HTTP bearer

Fetch grouped persona data from BigQuery.

Results are aggregated by market + job_role with summaries generated
directly from the query output.

## Query parameters

- `market` string, nullable: Filter results to a specific market segment
- `job_role` string, nullable: Filter results to a specific job role
- `limit` integer: Maximum number of market/role groups to return

## Response `200`

Successful Response

- PersonaGroupsResponse
  - `groups` PersonaGroup[], required
    - `society_id` string, required: Stable society identifier for this group
    - `society_key` string, nullable: Composite '{market}/{name}' key from the societies row. `society_id` is the UUID PK; the Gold layer, BigQuery persona_group and GCS prefix are keyed on this string instead, so callers reading those stores (e.g. the knowledge-graph viewer) must use it. None when the group's societies row is missing.
    - `source_mode` string, nullable: How the society was built: 'market' (web research), 'customer' / 'mixed' (Mode 2, from integrations). Authoritative (prefers the latest pipeline job's mode). Lets the UI gate Mode-2-only actions like 'add documents'. None when it can't be resolved.
    - `market` string, required
    - `job_role` string, required: Primary role within the market segment
    - `display_name` string, nullable: User-facing society name for UI rendering
    - `display_market` string, nullable: User-facing market label for UI rendering
    - `persona_count` integer, required: Number of individual personas in the group
    - `summary` string, required: Human-readable synopsis of the group
    - `experience_range` string, nullable: Human-friendly description of experience span
    - `representative_titles` string[]: Sample titles seen within the role
    - `key_characteristics` string[]: Sample traits/highlights
    - `seniority_levels` string[]
    - `departments` string[]
    - `teams` string[]
    - `notes_summary` string, nullable: Concatenated highlights from persona notes
    - `created_at` string, nullable: Society creation timestamp used for UI sorting
    - `gold_node_count` integer, nullable: Nodes in the society's Gold knowledge graph (keyed on `society_key`); 0 when it has none yet. None when the Gold table can't be read.
    - `gold_updated_at` string, nullable: When the society's Gold nodes last changed. None when it has none.
    - `sample_personas` PersonaSample[], nullable: Small preview of personas (name + avatar) for UI chips. Populated only when the caller opts in.
      - `name` string, required
      - `avatar` string, nullable
  - `total_groups` integer, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/evidenso/apis/persona-rag-api.md) - [All operations](https://skmtc.dev/evidenso/apis/persona-rag-api/llms.txt) - [OpenAPI document](https://skmtc.dev/evidenso/apis/persona-rag-api/revisions/86408c178d4f?raw)