---
title: "Get user stories (conversations)"
method: POST
path: "/dashboard/api/user-stories"
tags: ["Dashboard"]
---

# Get user stories (conversations)

`POST /dashboard/api/user-stories`

## Request

- Base URL: `https://api.agnost.ai`
- URL: `https://api.agnost.ai/dashboard/api/user-stories`
- Auth: one of:
  - HTTP bearer and API key in header `x-org-id`
  - API key in header `x-api-key`

## Request body

- UserStoriesListFilters
  - `time_range` '1min' | '1h' | '1d' | '1w' | '1m' | 'all'
  - `connection_type` union
    - string
    - string[]
  - `agent_name` union
    - string
    - string[]
  - `metadata_filters` object[]
    - `key` string
    - `value` string
  - `page` integer
  - `page_size` integer: Conversations, groups, or users per page. The dashboard requests 15 distinct group values at a time.
  - `search` string: Case-insensitive identifier search used to load matching search options.
  - `search_field` 'user_id' | 'conversation_id' | 'original_conversation_id' | 'user_email' | 'group_value': Structured identifier selected from User Stories search. Grouped requests accept only `group_value`.
  - `search_value` string: Exact value for the selected search field.
  - `group_by` UserStoriesGroupBy
    - `source` 'conversation_metadata' | 'user_metadata', required
    - `key` string, required: Metadata-map key to group by.
  - `sort` 'newest' | 'oldest'
  - `exclude_io` boolean: Omits event input/output payloads when true.
  - `allow_limited_preview` boolean: Dashboard-only flag for a small access-limited preview; programmatic clients should leave false.
  - `sentiment_ids` string[]: Restricts conversations to events matching any selected intent id.
  - `sop_ids` string[]: Restricts conversations to events matching any selected violation id.
  - `group_level` 'groups' | 'users' | 'conversations': When `group_by` is present, returns metadata groups by default, users within `group_value`, or conversations for `group_user_key`.
  - `group_value` string: Required when `group_level` is `users` or `conversations`.
  - `group_user_key` string: Opaque user key returned by grouped users; required for `group_level: conversations`.

## Response `200`

Recent conversations, metadata groups, or users within a metadata group

- UserStoriesResponse: Returns `conversations`, `groups`, or `users` according to the grouping request.
  - `conversations` object[]
  - `groups` UserStoriesGroupSummary[]
    - `value` string, required
    - `conversation_count` integer, required
    - `user_count` integer, required
    - `message_count` integer, required: Distinct captured events across the group's eligible conversations, including tool events.
    - `intent_count` integer, required
    - `intent_labels` string[], required
    - `violation_count` integer, required
    - `violation_labels` string[], required
    - `last_active` string, date-time, required
    - `cost_metadata` UserStoriesCostMetadata[]
  - `users` UserStoriesUserSummary[]
    - `key` string, required
    - `user_id` string
    - `label` string, required
    - `representative_conversation_id` string, required
    - `conversation_count` integer, required
    - `message_count` integer, required: Distinct captured events across the user's eligible conversations, including tool events.
    - `intent_count` integer, required
    - `intent_labels` string[], required
    - `violation_count` integer, required
    - `violation_labels` string[], required
    - `last_active` string, date-time, required
    - `cost_metadata` UserStoriesCostMetadata[]
  - `user_summaries` UserStoriesVisibleUserSummary[]: Full filtered-history metrics for users on the current ungrouped interactive page. Empty for grouped or limited-preview responses. Metrics degrade to zero values when optional aggregation is unavailable.
    - `key` string, required: Stable `user:<user_id>` key, or `conversation:<conversation_id>` for an anonymous conversation.
    - `conversation_count` integer, required
    - `message_count` integer, required: Distinct captured events across the user's eligible conversations, including tool events.
    - `intent_count` integer, required
    - `intent_labels` string[], required
    - `violation_count` integer, required
    - `violation_labels` string[], required
    - `cost_metadata` UserStoriesCostMetadata[]
  - `group_value` string
  - `overlapping` boolean: Metadata arrays may place a conversation in more than one group.
  - `page` integer
  - `page_size` integer
  - `total_pages` integer
  - `has_more` boolean: True when one lookahead row proves that another page is available.
  - `partial_data` boolean: True when optional hydration or enrichment failed and the returned page is incomplete.

## Changes

- **2026-11-03** `a61431b48f36`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agnost/apis/agnost-ai-api/changes/dashboard/api/user-stories/post.md)

---

[API](https://skmtc.dev/agnost/apis/agnost-ai-api.md) - [All operations](https://skmtc.dev/agnost/apis/agnost-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agnost/apis/agnost-ai-api/revisions/a61431b48f36?raw)