Response Schema

Shape of job objects, summaries, signals, and audio quality.

The Amplifier API produces two response shapes:

• Model jobs (POST /v2/models/{model_name}/analyze) — multi-sign result with a summary wrapper, a signals[] array, audio_quality, and extended_metrics. See Model API.
• Sign jobs (POST /v2/signs/{sign_name}/analyze) — single-signal result with a singular signal object and audio_quality. See Sign API.

Both endpoints return the full job object immediately (job_id, status: queued, result: null). Retrieve the completed result with GET /v2/jobs/{job_id}, or receive it via webhook.

When a request fails, the API returns a JSON object with code, message, and status — see Errors.

For workflow and display rules, see Interpreting Results.

Model response

Analyze submit and GET /v2/jobs/{job_id} share the same job envelope. At submit time status is queued and result is null. The table below is the canonical field list.

Job response

GET /v2/jobs/{job_id} returns the job status and, when complete, the full analysis result.

Both model_name and sign_name may appear on the same object. Treat the unused discriminator as null; do not require it to be omitted.

Note status is one of queued, running, done, failed, or timed-out. Nullable fields — completed_at, result, audio_sample_rate, and the unused discriminator — may be null.

result contains:

{
  "job_id": "189bce4a-52cb-4e60-8586-cef89e719109",
  "status": "done",
  "created_at": "2026-02-22T09:14:00Z",
  "completed_at": "2026-02-22T09:14:03Z",
  "job_type": "model",
  "api_version": "v2",
  "model_name": "pulse",
  "sign_name": null,
  "audio_content_type": "audio/wav",
  "audio_size_bytes": 876032,
  "audio_duration_seconds": 27.4,
  "result": {
    "summary": { ... },
    "signals": [ ... ],
    "audio_quality": { ... },
    "extended_metrics": [ ... ]
  }
}

Timestamps

Type: created_at and completed_at are ISO 8601 datetimes; RFC 3339–compatible parsing is recommended.

Variability: The API may return:

• A timezone designator: Z (UTC) or numeric offset ±hh:mm, or omit the designator in some responses.
• Fractional seconds at variable precision (milliseconds, microseconds, and so on).

UTC: Values with a Z suffix are UTC. When no offset appears, treat the timestamp as UTC.

Client guidance: Use a standard ISO 8601-compatible datetime parser. Prefer parsing over string comparison, and allow for a varying number of fractional digits.

Both of these forms are valid.

With Z, no fractional seconds:

"created_at": "2026-02-22T09:14:00Z",
"completed_at": "2026-02-22T09:14:03Z"

With fractional seconds, no Z:

"created_at": "2026-03-28T01:05:35.943000",
"completed_at": "2026-03-28T01:05:38.120500"

Job status: failed

This section covers both terminal outcomes that end without a result: failed and timed-out.

When status is "failed" or "timed-out", processing ended without a result. For a valid job_id on your account, GET /v2/jobs/{job_id} still returns 200 OK with a job object — these outcomes are expressed in status, not via a 4xx HTTP code.

Poll until status is done, failed, or timed-out, then branch:

• done: result contains the full analysis.
• failed: result is typically null; completed_at may also be null. For the failure reason, check your operational logs or contact support — the job object does not include a structured error code.
• timed-out: processing did not complete in time; result and completed_at are null. Submit a new job to retry.

404 Not Found applies when the job is unknown or belongs to a different account — see Jobs API.

summary object

result.summary is the primary object for routing decisions. Read it first.

overall_level reflects the highest level value across all signals in the bundle. recommended_action is derived from the full distribution of signal levels — not from overall_level alone. See Recommended action logic for the derivation.

{
  "overall_level": "elevated",
  "recommended_action": "escalate",
  "flagged_count": 3,
  "primary_signals": ["stress", "anxiety", "fatigue"],
  "description": {
    "summary": "Voice patterns suggest elevated indicators for stress and anxiety...",
    "vocal_features": [ ... ]
  }
}

signals array

signals contains one entry per sign in the model bundle.

[
  {"name": "stress", "label": "Stress", "score": 0.81, "level": "elevated", "flagged": true},
  {"name": "anxiety", "label": "Anxiety", "score": 0.71, "level": "elevated", "flagged": true},
  {"name": "fatigue", "label": "Fatigue", "score": 0.54, "level": "consider", "flagged": true}
]

For display rules and field usage guidance, see Display guidelines.

description object

description is nested inside summary. It contains a machine-generated plain-text summary and a structured array of annotated vocal feature values.

Surface description in care-staff interfaces. For the full display rules, see Display guidelines.

vocal_features array

Each entry in vocal_features describes a single acoustic measurement extracted from the recording.

{
  "summary": "Voice patterns suggest elevated stress and fatigue indicators...",
  "vocal_features": [
    {
      "feature": "speech_rate",
      "label": "Speech Rate",
      "value": 3.2,
      "unit": "syllables/s",
      "value_interpretation": "reduced"
    },
    {
      "feature": "voice_shimmer",
      "label": "Voice Shimmer",
      "value": 0.041,
      "unit": "dB",
      "value_interpretation": "slightly elevated"
    }
  ]
}

audio_quality object

audio_quality scores the recording and lists issue codes. Use them to keep the result or re-record. File metadata is on the job: audio_size_bytes, audio_duration_seconds, audio_content_type.

issues, voice_percentage, and audio_clarity are coherent: when a score is below its threshold, the corresponding issue code will typically be present in issues.

{
  "issues": [],
  "voice_percentage": 82.4,
  "audio_clarity": 74.1
}

Example with quality issues detected:

{
  "issues": ["high_background_noise", "insufficient_speech"],
  "voice_percentage": 21.3,
  "audio_clarity": 38.6
}

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 — see Audio quality issue codes for the recommended action for each code.

extended_metrics array

extended_metrics contains wellness metric scores derived from the voice recording. The set of metrics returned depends on the model. For metric definitions, see Extended Metrics.

[
  {
    "metric_id": "anxious-mood",
    "label": "Anxious Mood",
    "score_mean": 0.72,
    "score_std": 0.08,
    "low_anchor": "tranquil",
    "high_anchor": "panicked"
  },
  {
    "metric_id": "vad-valence",
    "label": "Emotional Valence",
    "score_mean": 0.38,
    "score_std": 0.05,
    "low_anchor": "negative",
    "high_anchor": "positive"
  }
]

Sign response

POST /v2/signs/{sign_name}/analyze returns the same job object envelope (see Job response above), but with job_type: "sign", a non-null sign_name, model_name typically null, and a structurally different result interior.

The result object uses a singular signal object instead of summary plus signals[]:

{
  "job_id": "4a8f12c9-e7b2-4d3a-9f1c-8b6d2e5a7c0f",
  "status": "done",
  "job_type": "sign",
  "api_version": "v2",
  "model_name": null,
  "sign_name": "stress",
  "result": {
    "signal": { ... },
    "audio_quality": { ... }
  }
}

signal object

signal is a single object, not an array, containing the full result for the requested sign. Where the model response places description and recommended_action on the summary wrapper, the sign response places them directly on signal.

recommended_action is derived from this sign’s level alone — not aggregated across a bundle. See Recommended action logic.

description contains an LLM-generated plain-text summary of the acoustic findings and a structured vocal_features array. The same display rules apply: surface it in care-staff interfaces. On the inconclusive path, summary contains a standard inconclusive message and vocal_features is empty.

{
  "name": "stress",
  "label": "Stress",
  "score": 0.81,
  "level": "elevated",
  "flagged": true,
  "recommended_action": "escalate",
  "description": {
    "summary": "Voice patterns suggest elevated stress indicators...",
    "vocal_features": [
      {
        "feature": "speech_rate",
        "label": "Speech Rate",
        "value": 3.2,
        "unit": "syllables/s",
        "value_interpretation": "reduced"
      }
    ]
  }
}

Use job_type to select the correct result parser:

For display rules, see Display guidelines.