---
title: "Evaluate"
method: POST
path: "/v1/evaluate"
tags: ["Evaluate"]
---

# Evaluate

`POST /v1/evaluate`

Submit a call or chat for evaluation.

## Headers

- `X-API-Key` string, required

## Request body

- union
  - CallRequestUsingAgentId
    - `agent_id` string, required — ID of the agent associated with the call
    - `recording_url` string, uri, nullable — URL to the recording file (supported formats: .mp3, .mp4, .wav, .m4a)
    - `recording_base64` string, nullable — Base64 encoded recording file in data URL format (supported formats: .mp3, .mp4, .wav, .m4a)
    - `start_time_utc` string, date-time, required — When the call started, in UTC ([python] log: datetime.now(timezone.utc) at call start)
    - `participants` Participant[], required — List of call participants
      - `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
    - `call_direction` 'INBOUND' | 'OUTBOUND' — Enum representing the direction of a call.
    - `interface` 'PHONE' | 'WEB' — Enum representing the interface used for a call.
    - `transcript_url` string, uri, nullable — URL to the transcript file (supported formats: .json)
    - `transcript` TranscriptEntryRequest[], nullable — Transcript of the call in text format
      - `start_offset_ms` integer, required — Start offset of the utterance in milliseconds
      - `end_offset_ms` integer, required — End offset of the utterance in milliseconds
      - `speaker` 'AGENT' | 'USER' | 'DIGITAL_HUMAN' | 'agent' | 'digital_human', required — Role of a participant in a call or simulated conversation.
      - `utterance` string, required — Transcribed text of the utterance
      - `filler_utterance` boolean, nullable — Whether the utterance is a filler utterance
    - `tool_calls` ToolCallData[], nullable — List of tool calls made during the call
      - `name` string, required
      - `start_offset_ms` integer, required
      - `description` string, nullable
      - `parameters` object, nullable
      - `output` unknown
    - `events` Event[], nullable — List of events that occurred during the call
      - `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
    - `tags` string[], nullable — List of tags associated with the call
    - `trace_id` string, nullable — Trace ID of the call
    - `created_at` string, date-time, nullable — When this request was created (defaults to now in UTC)
    - `metadata` object, nullable — Additional metadata associated with the evaluation
    - `webhook_tag` string, nullable — Tag of the webhook to send the evaluation to
    - `custom_metrics` string[], nullable — List of additional custom metrics to be used in the call
    - `custom_metric_tags` string[], nullable — Specify one or more tags to include all custom metrics associated with those tags. This allows you to run groups of related custom metrics without listing each individually.
    - `label` string, nullable — Label of the agent to use for the evaluation (determines which prompt and knowledge base to use and defaults to the `production` label if not provided)
    - `enable_phrase_latencies` boolean, nullable — Whether to enable phrase-level latency tracking for this call
    - `conversation_ended_by` 'AGENT' | 'USER' | 'DIGITAL_HUMAN' | 'agent' | 'digital_human' — Role of a participant in a call or simulated conversation.
    - `multichannel` boolean, nullable — Whether the participants of the call are on different audio channels
  - CallRequestUsingExternalAgentId
    - `external_agent_id` string, required — The external ID of your agent to associate with the call
    - `recording_url` string, uri, nullable — URL to the recording file (supported formats: .mp3, .mp4, .wav, .m4a)
    - `recording_base64` string, nullable — Base64 encoded recording file in data URL format (supported formats: .mp3, .mp4, .wav, .m4a)
    - `start_time_utc` string, date-time, required — When the call started, in UTC ([python] log: datetime.now(timezone.utc) at call start)
    - `participants` Participant[], required — List of call participants
      - `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
    - `call_direction` 'INBOUND' | 'OUTBOUND' — Enum representing the direction of a call.
    - `interface` 'PHONE' | 'WEB' — Enum representing the interface used for a call.
    - `transcript_url` string, uri, nullable — URL to the transcript file (supported formats: .json)
    - `transcript` TranscriptEntryRequest[], nullable — Transcript of the call in text format
      - `start_offset_ms` integer, required — Start offset of the utterance in milliseconds
      - `end_offset_ms` integer, required — End offset of the utterance in milliseconds
      - `speaker` 'AGENT' | 'USER' | 'DIGITAL_HUMAN' | 'agent' | 'digital_human', required — Role of a participant in a call or simulated conversation.
      - `utterance` string, required — Transcribed text of the utterance
      - `filler_utterance` boolean, nullable — Whether the utterance is a filler utterance
    - `tool_calls` ToolCallData[], nullable — List of tool calls made during the call
      - `name` string, required
      - `start_offset_ms` integer, required
      - `description` string, nullable
      - `parameters` object, nullable
      - `output` unknown
    - `events` Event[], nullable — List of events that occurred during the call
      - `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
    - `tags` string[], nullable — List of tags associated with the call
    - `trace_id` string, nullable — Trace ID of the call
    - `created_at` string, date-time, nullable — When this request was created (defaults to now in UTC)
    - `metadata` object, nullable — Additional metadata associated with the evaluation
    - `webhook_tag` string, nullable — Tag of the webhook to send the evaluation to
    - `custom_metrics` string[], nullable — List of additional custom metrics to be used in the call
    - `custom_metric_tags` string[], nullable — Specify one or more tags to include all custom metrics associated with those tags. This allows you to run groups of related custom metrics without listing each individually.
    - `label` string, nullable — Label of the agent to use for the evaluation (determines which prompt and knowledge base to use)
    - `enable_phrase_latencies` boolean, nullable — Whether to enable phrase-level latency tracking for this call
    - `conversation_ended_by` 'AGENT' | 'USER' | 'DIGITAL_HUMAN' | 'agent' | 'digital_human' — Role of a participant in a call or simulated conversation.
    - `multichannel` boolean, nullable — Whether the participants of the call are on different audio channels

## Response `200`

Successful Response

- EvaluateCallResponse
  - `status` string, required
  - `call_id` string, required
  - `message` string, required

## 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/18bc44e35414/schema)