Skip to navigation
Observability

Add Calls

Submit a call recording and/or transcript for analysis. At least one of recording_url or transcript is required.

You sendWhat happens
recording_url + transcriptAudio metrics run on the recording; transcript metrics run on your transcript.
recording_url onlyRubricHQ transcribes the recording, then runs every metric.
transcript onlyTranscript metrics only. The call is stored as observation_type: "text" and audio metrics are not evaluated.

By default the call is scored on every metric enabled for the agent. Pass metric_ids to score it on only those metrics.

The response returns immediately with analysis_status: "pending". Poll GET /calls/{id} until it is completed, failed, or skipped.

Authentication

AuthorizationBearer

API key from RubricHQ Settings → API Keys. Send it as: Authorization: Bearer <YOUR_API_KEY>.

Request

This endpoint expects an object.
call_identifierstringRequired
Required. Your unique ID for this call. Used for deduplication and retrieval.
agent_idintegerRequired
Required. RubricHQ agent ID to associate with this call.
client_idintegerOptional

Optional. RubricHQ client (workspace) ID. Defaults to the workspace your API key belongs to.

recording_urlstringOptionalformat: "uri"

Publicly accessible URL to the audio recording (WAV, MP3, or M4A). Required if no transcript is provided. RubricHQ will download and store this securely. Needed for audio-based metrics (latency, interruptions, silence, WPM). Omit it for text-only calls — the call is then stored with observation_type: "text" and audio metrics are not evaluated. For the most accurate per-speaker audio metrics, send a stereo recording with the agent on the left channel and the caller on the right.

transcriptlist of objectsOptional

The conversation as an ordered list of turns. Required if no recording_url is provided. Each turn is an object:

FieldTypeDescription
rolestringOne of "AI Assistant", "User", "Function Call", or "Function Call Result".
contentstringWhat was said in this turn. Empty for tool-call turns.
start_timenumberSeconds from the start of the call when the turn began.
end_timenumberSeconds from the start of the call when the turn ended.
dataobjectOnly on tool-call turns. Carries id, name, and arguments (on "Function Call") or result (on "Function Call Result").
observation_typeenumOptionalDefaults to voice

Optional — you rarely need to send it. voice (default) is a spoken call; text is a chat or other text-only conversation. A call sent with a transcript and no recording_url is stored as text automatically.

Allowed values:
tagstringOptional

Optional. Short tag for grouping/filtering calls.

call_directionenumOptionalDefaults to inbound

Optional (defaults to inbound). Whether the call was initiated by the agent (outbound) or the customer (inbound).

Allowed values:
call_end_reasonstringOptional

Optional. How the call ended (e.g. Completed, Dropped, Transferred).

customer_numberstringOptional

Optional. Customer phone number. e.g. 978-987-9876

duration_secondsintegerOptional
Optional. Total call duration in seconds.
call_timestampdatetimeOptional

Optional. When the call occurred (ISO 8601) in your system. Defaults to the time the call was added in our system if omitted.

labelstringOptional

Optional. Free-text label for this call (visible in the dashboard).

metric_idslist of integersOptional

Optional. Score this call on only these metrics (IDs from GET /metrics — built-in or your own). Leave it out to score the call on every metric enabled for the agent.

An ID that can’t be scored on this call — it doesn’t exist in your workspace, isn’t enabled for the agent, or is an audio metric and there is no recording_url — is skipped, and the response lists it in ignored_metric_ids so you can spot a stale ID. The call is always ingested. If none of the IDs can be scored, the call is scored as if metric_ids had been left out (every metric enabled for the agent), and all of them appear in ignored_metric_ids.

Every metric that runs consumes credits from your workspace balance.

metadatamap from strings to anyOptional

Optional. Arbitrary key-value pairs stored with the call (visible in the dashboard).

Response

Call accepted for analysis
idintegerOptional
Internal RubricHQ call ID.
call_identifierstringOptional
Your provided call identifier.
observation_typeenumOptional

voice when the call has a recording; text for a transcript-only call.

Allowed values:
analysis_statusenumOptional
  • pending — analysis queued
  • processing — analysis in progress
  • computed — the audio pass is done; transcript and custom metrics may still be scoring. Not final — keep polling.
  • completed — every metric has a result (final)
  • failed — analysis encountered an error (final)
  • skipped — not analyzed, e.g. the workspace is out of credits (final)

Stop polling on completed, failed, or skipped.

transcription_statusenumOptional
  • pending — the recording has not been transcribed yet
  • processing — transcription in progress
  • completed — a transcript is available (generated from the recording, or the one you provided on a transcript-only call)
  • failed — transcription failed
Allowed values:
call_directionenumOptional
Allowed values:
call_end_reasonstring or nullOptional
customer_numberstring or nullOptional
duration_secondsinteger or nullOptional
labelstring or nullOptional
tagstring or nullOptional
call_timestampdatetime or nullOptional
recording_urlstring or nullOptional

Presigned URL to the stored recording (valid for a limited time — fetch the call again for a fresh one). null until RubricHQ has finished storing the recording, and always null for transcript-only calls.

metric_idslist of integersOptional
The metric selection this call is scored on, after dropping any IDs that could not be scored. Empty means "every metric enabled for the agent".
ignored_metric_idslist of integersOptional

Only on the POST /calls response, and only when it is not empty: the IDs from your metric_ids that could not be scored on this call and were skipped.

metadatamap from strings to anyOptional
created_atdatetimeOptional
When the call was added to RubricHQ.
agentobjectOptional

Errors

404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error