---
title: "Query Observability Conversations"
method: GET
path: "/v1/observability/conversations"
tags: ["Observability Conversations"]
---

# Query Observability Conversations

`GET /v1/observability/conversations`

Query production conversations for this organization.

Omit `group_by` for rows, newest first. Set it for counts per group: by
status, agent, label, day, interface, direction, ended_by, a `metadata_path`,
or `metric_value` for how a metric came out. Filters apply either way, so one
narrowing answers both "show me" and "how many".

## Query parameters

- `status` string[], nullable — e.g. COMPLETED, SYSTEM_ERROR
- `agent_ids` integer[], nullable
- `label_ids` string[], nullable
- `initiation_direction` string[], nullable — inbound, outbound
- `caller_number` string, nullable — E.164
- `duration_min` integer, nullable — Minimum duration in ms
- `duration_max` integer, nullable — Maximum duration in ms
- `tags` string[], nullable
- `conversation_ids` string[], nullable
- `interface` string[], nullable
- `label` string, nullable — Label text, resolved to an id
- `metadata_path` string, nullable — Metadata key, e.g. restaurant_code
- `metadata_value` string, nullable
- `metric_name` string, nullable — Required when group_by is metric_value
- `metric_id` string, uuid, nullable
- `metric_value` string[], nullable — Keep only conversations whose metric came out one of these values. Needs metric_name or metric_id. This is the filter, not the grouping.
- `metric_min` number, nullable — Numeric metrics: keep results at or above this
- `metric_max` number, nullable — Numeric metrics: keep results at or below this
- `group_by` 'status' | 'agent' | 'label' | 'day' | 'interface' | 'direction' | 'ended_by' | 'metadata' | 'metric_value', nullable — Omit for rows; set for counts
- `last` '1day' | '3days' | '7days' | '30days' | '90days' | 'all'
- `sort_order` 'asc' | 'desc'
- `page_size` integer
- `page` integer

## Headers

- `X-API-Key` string, required

## Response `200`

Successful Response

- ConversationsResponse
  - `total` integer, required — Everything matching the filters, not just this page
  - `group_by` string, nullable
  - `data` ObsConversation[]
    - `obs_conversation_id` string, uuid, required
    - `created_at` string, date-time, nullable
    - `organization_id` string, uuid, required
    - `agent_id` integer, required
    - `label_id` string, uuid, nullable
    - `status` 'INITIALIZING' | 'QUEUED' | 'READY' | 'DISPATCHED' | 'RUNNING' | 'CONVERSATION_ENDED' | 'EVALUATING' | 'COMPLETED' | 'NO_CONNECTION' | 'NO_ANSWER' | 'CALL_DROPPED' | 'OUT_OF_FUNDS' | 'SYSTEM_ERROR' | 'CUSTOM_ERROR' | 'CANCELLED' | 'INCOMPLETED' | 'REJECTED' | 'INSUFFICIENT_FUNDS' — Enum representing the possible states of a conversation.
    - `multichannel_requested` boolean, nullable
    - `tool_calls` ConversationToolCalls[], nullable
      - `tool_name` string
      - `start_offset_ms` integer
      - `tool_input` object
      - `tool_output` string
    - `initiation_direction` 'INBOUND' | 'OUTBOUND' — Enum representing the direction of a call.
    - `tags` string[], nullable
    - `interface` 'PHONE' | 'WEB' — Enum representing the interface used for a call.
    - `metadata` object, nullable
    - `events` Event[], nullable
      - `title` string, required — Title of the event
      - `start_offset_ms` integer, required — Start offset of the event in milliseconds
      - `description` string, nullable — Description of the event
      - `end_offset_ms` integer, nullable — End offset of the event in milliseconds
      - `tags` string[], nullable — List of tags associated with the event
      - `metadata` object, nullable — Additional metadata associated with the event
    - `conversation_ended_by` 'AGENT' | 'USER' | 'DIGITAL_HUMAN' | 'agent' | 'digital_human' — Role of a participant in a call or simulated conversation.
    - `trace_ids` string[]
    - `start_time_utc` string, date-time, nullable
    - `duration_ms` integer, nullable
    - `participants` Participant[], nullable
      - `role` 'AGENT' | 'USER' | 'DIGITAL_HUMAN' | 'agent' | 'digital_human' — Role of a participant in a call or simulated conversation.
      - `name` string, nullable
      - `spoke_first` boolean
      - `phone_number` string, nullable
    - `submitted_recording_url` string, nullable
    - `submitted_transcript_url` string, nullable
    - `submitted_transcript` TranscriptEntry[], nullable
      - `start_offset_ms` integer, required
      - `end_offset_ms` integer, required
      - `speaker` string, required
      - `utterance` string, required
      - `filler_utterance` boolean, nullable
    - `bluejay_recording_filepath` string, nullable
    - `bluejay_transcript_filepath` string, nullable
    - `bluejay_transcript` object[], nullable
    - `bluejay_translated_transcript` object[], nullable
    - `bluejay_words_transcript` object[], nullable
    - `bluejay_reference_transcript` object[], nullable
    - `bluejay_translated_transcript_filepath` string, nullable
    - `bluejay_words_transcript_filepath` string, nullable
    - `bluejay_reference_transcript_filepath` string, nullable
    - `error_code` string, nullable
    - `error_message` string, nullable
    - `error_details` object, nullable
  - `breakdown` Bucket[]
    - `group` string, required — The grouped value, or the metric value when grouping by it
    - `count` integer, required
    - `avg_duration_ms` number, nullable — Conversation groupings only
    - `edited_count` integer, nullable — Metric groupings only
  - `groups_truncated` boolean — True when more groups matched than were returned
  - `metric_name` string, nullable
  - `metric_type` string, nullable
  - `not_applicable` integer, nullable
  - `average` number, nullable — Numeric metrics only
  - `page` integer, nullable
  - `page_size` integer, nullable
  - `unreadable_skipped` integer — Rows on this page too incomplete to read, dropped rather than failing it

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/getbluejay/apis/bluejay-api.md) · [All operations](https://skmtc.net/getbluejay/apis/bluejay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getbluejay/bluejay-api/revisions/f48cef80963f/schema)