Interpreting Results

Submitting audio returns a job_id immediately. Poll GET /v2/jobs/{job_id} or use a webhook until status is a terminal value: done or failed.

• Model analyze — POST /v2/models/{model_name}/analyze. When status is done, result contains summary, signals[], audio_quality, and extended_metrics. See Model API job results.
• Sign analyze — POST /v2/signs/{sign_name}/analyze. When status is done, result contains a single signal and audio_quality. See Sign API job results.

When status is failed, result is usually null; see Job status: failed. For field-level reference see Response Schema. For model IDs and tiers see Models.

Named model bundles combine models with different evidence tiers (Established, Emerging, Investigational). Interpret each signal using its model’s tier — see Model Overview and Models. For the product disclaimer and how tiers fit together, see Introduction.

Response structure overview

job
├── job_id               — Unique job identifier
├── status               — pending | running | done | failed  (poll until done | failed)
├── job_type             — "model" | "sign"
├── model_name           — Set when job_type is "model"; null otherwise
├── sign_name            — Set when job_type is "sign"; null otherwise
├── created_at           — ISO 8601; format varies — see Response Schema → Timestamps
├── completed_at         — null while pending/running; when done vs failed see Schema
├── audio_content_type   — MIME type of submitted audio
├── audio_size_bytes     — Size of submitted audio
├── audio_duration_seconds
└── result               — Full analysis when status is done; typically null when failed
    ├── summary          — Aggregate view; primary routing object (model jobs only)
    │   ├── overall_level
    │   ├── recommended_action
    │   ├── flagged_count
    │   ├── primary_signals
    │   └── description  — Natural language summary and vocal features
    │       ├── summary  — Narrative text of voice pattern findings
    │       └── vocal_features[]
    ├── signals[]        — Array of per-sign results (model jobs only)
    ├── signal           — Single signal object (sign jobs only)
    ├── audio_quality    — Recording quality scores and issue codes
    └── extended_metrics[]  — model jobs only

Model API job results

If you use POST /v2/models/{model_name}/analyze, send multipart audio with the model name in the URL path. The API returns a job object right away (job_id, status: running, result: null until processing finishes). Poll GET /v2/jobs/{job_id} or use a webhook until status is done or failed.

On the outer job object, job_type is "model", model_name is the name you requested, and sign_name is null. When status is done, result contains: summary (with overall_level, recommended_action, flagged_count, primary_signals, and description), signals[] (one entry per sign in the bundle), audio_quality, and extended_metrics. Read result.summary.recommended_action for routing, then result.signals[] for per-sign detail. When status is failed, result is usually null; see Job status: failed.

Field-level detail: Model API. The same display and compliance rules apply when presenting outputs.

Sign API job results

If you use POST /v2/signs/{sign_name}/analyze, send multipart audio with the sign name in the URL path. The API returns a job object right away (job_id, status: running, result: null until processing finishes). Poll GET /v2/jobs/{job_id} or use a webhook until status is done or failed.

On the outer job object, job_type is "sign", sign_name is the name you requested, and model_name is null. When status is done, result contains one signal object (recommended_action, level, flagged, description, and scores) and audio_quality. There is no top-level summary and no signals[] array; use result.signal for routing and UI. Read result.signal.recommended_action, result.signal.level, and result.signal.flagged for routing. When status is failed, result is usually null; see Job status: failed.

Field-level detail: Sign API. The same display and compliance rules apply when presenting outputs.

The summary object

summary is the primary object for routing decisions. It aggregates all signal scores into a single recommended action and level.

Read summary first: if recommended_action is none or monitor, your workflow may not need to inspect individual signals at all. When the action is consider, review, or escalate, check primary_signals to identify which conditions are driving the result, then inspect the corresponding entries in signals for score detail.

For field definitions, see Response Schema.

The description object

summary.description provides a narrative of the voice analysis alongside a set of interpretable acoustic features. It has two fields:

• summary — Describes the voice pattern findings for this recording. Contains no PII. See Display Guidelines for display guidance.
• vocal_features — An array of the acoustic features most relevant to the analysis. Each entry describes one measured voice characteristic.

Each item in vocal_features has the following shape:

vocal_features is appropriate for display to qualified care staff as supporting context for the summary narrative.

Signal levels

Signal levels are applied both to individual models in the signals array and to overall_level in summary. The five risk-derived levels are none, low, consider, moderate, and elevated, each mapping to a score range and a clinical interpretation, and there is an additional neutral inconclusive level for cases where the analysis cannot complete to the usual quality standards. Use none to represent a clear “within normal range” result; use inconclusive when there is no clear signal at all and you prefer to re-record or collect more information rather than making a routing decision.

Score-to-level mapping uses a distribution-based calibration unique to each model, rather than fixed numeric ranges. Use level — not raw score — for routing and display logic. For the full trigger logic table, see Levels & Actions — Recommended Action Trigger Logic.

Recommended action logic

recommended_action aggregates all signal levels (not one model alone). See Levels & Actions — Recommended Action Trigger Logic for the full trigger table.

Why review includes two or more at consider: Co-occurring signals at the consider level can warrant provider attention even when each alone would only trigger a consider action. One signal at consider → consider; two or more at consider → review.

When recording conditions may be below optimal for analysis, the API may return recommended_action: "inconclusive" and overall_level: "inconclusive". Treat this as "no clear signal; prefer re-recording or collecting more information" rather than as a monitoring, review, or escalation trigger.

The signals array

signals contains one entry per sign in the model bundle. Each entry describes the sign's output for this specific audio sample.

In most integrations, filter by flagged: true to surface only the conditions the API considers noteworthy for this recording. Unflagged signals (flagged: false) are still valuable for logging and analytics, even when not shown to end users — they establish a baseline for detecting changes over time.

For field definitions, see Response Schema. For display guidance, see Display Guidelines.

The audio_quality object

audio_quality provides quality scores for the recording and flags any conditions so you can assess when to use the result or re-record. It contains issues (array of issue codes), voice_percentage (0–100, percentage of recording with active speech), and audio_clarity (0–100, background noise quality score). File-level metadata such as size, duration, and format is available on the job object fields.

For field definitions and issue codes, see Response Schema — audio_quality Object and Audio Requirements.

When issues is non-empty, signals may still be returned. Use the issue codes to decide whether to act on the result or re-record; for critical routing decisions, prefer re-recording when quality issues are present.

Display Guidelines

Amplifier outputs include fields intended for internal system logic and fields appropriate for end-user display. Mixing these up is the most common integration mistake.

What to display:

• level — Use this as your primary display primitive. It conveys meaning without revealing the raw score.
• label — The human-readable condition name.
• flagged — Use to filter which signals appear in a user-facing view.

Keep for internal use:

• score — Use level and label for display; keep raw score values for internal logging and analytics.
• description.summary — Auto-generated narrative; surface it only after review by qualified care staff, not as direct patient-facing output. Located at summary.description.summary in model responses, signal.description.summary in sign responses.
• name — Stable external sign identifier; safe to use in application logic (e.g. signal.name === "stress"). label is the human-readable display name derived from it.

Use the display labels below for patient or end-user display. flagged is true when a signal's level is consider, moderate, or elevated.

Use language that is informational and non-diagnostic; do not use clinical diagnostic terms.

Handling errors

When the API returns a non-200 response, check the HTTP status code before retrying. For the full list of error codes, retry guidance, and exponential backoff examples, see Error Reference.