Inworld Request IDs: Trace a Voice API Attempt

“The voice failed during a call” is a difficult support report to investigate. One conversation can contain several speech requests, a canceled reply and a retry. A business call ID identifies the conversation, but it may not identify the provider operation that needs attention.

Inworld's October 5, 2026 product update documents an x-request-id response header and an optional x-inworld-client-request-id supplied by your application across Inference, text-to-speech and speech-to-text. It says either identifier can help its support team trace a request. This guide reviews that capability on October 17; it is not a new release today. Inworld product log.

An Inworld API request ID belongs in a small attempt record linking your application's turn to the request it submitted and the response it received. That helps locate evidence. It does not prove that a caller heard the audio, a retry is safe or a business action completed.

Burki's current Inworld TTS integration does not expose a verified request-header tracing control or a saved response-header field in its editor. Its TTS context and usage evidence are separate from these HTTP identifiers. The direct-provider method below is an integration design, with a separate Burki review path at the end.

Download the free request-ID worksheet. It includes an original fictional attempt timeline and a support-report template. No API request, speech generation or support message was sent for this article. The worksheet is free; provider usage and production calls are separate.

Keep the identifiers at their own level

Use a small hierarchy instead of one field called request_id for everything:

The local fields in this table are an application design, not mandatory Inworld field names. Choose a convention your team can read consistently. A failed first attempt and a successful second attempt should remain two records under one turn, rather than overwriting each other.

Avoid placing a caller's name, email, telephone number or account reference inside the client correlation value. An opaque random identifier can locate an internal record without repeating its contents in headers and logs. The mapping itself still needs appropriate access and retention controls.

The diagram is illustrative. No displayed identifier comes from a real customer, production call or executed provider request.

Prepare the capture point before an authorized request

For a direct HTTP integration, identify the part of your application that creates the request and receives its response. The current non-streaming TTS reference uses POST /tts/v1/voice, with explicit text, model and voice configuration. Its JSON response includes generated audio and usage; HTTP headers are a separate part of the response. Synthesis API contract.

Keep the credential separate from correlation. Inworld's server-side documentation uses the copied Basic credential as supplied, without encoding it again. Do not include authorization headers in a diagnostic export. Authentication conventions, credential security.

An integration would follow this sequence:

1. Create the local attempt record before handing the operation to the network client.
2. Give it an opaque correlation value and add that value to the optional client request-ID header.
3. After a response, copy the returned server request-ID header when present.
4. Record the HTTP outcome and the separately observed application result.
5. If no response arrives, retain the local attempt and mark the server identifier unknown.

These header fragments show the two sides, not an executed client:

Before an authorized request:
x-inworld-client-request-id: <opaque-local-attempt-id>

After a received response:
x-request-id: <returned-provider-value-or-unknown>

Use the returned value as supplied. Do not try to recreate it from a timestamp, your local UUID or a neighboring request. Do not assume the two identifiers will be identical. The public product update supplies the header names and correlation purpose; verify any format or size constraints in the current client contract before enforcing your own assumptions. Header announcement.

Store status separately from the identifier

A useful attempt record answers both “Which operation?” and “What did we observe?” Keep those questions in separate fields. For example:

{
  "conversation_ref": "demo-conversation-01",
  "turn_ref": "reply-03",
  "attempt_ref": "opaque-attempt-a",
  "provider_request_id": null,
  "outcome": "response_not_observed",
  "generated_audio_available": "unknown",
  "application_playback": "not_observed",
  "business_action": "not_part_of_this_request"
}

This is an original fictional record shape, not an Inworld API schema. An absent server ID is represented as unknown, not as proof that no request reached the provider. Likewise, an ID from an error response does not convert that response into a successful synthesis.

If your application receives a successful HTTP response, still validate the response your chosen endpoint promises. A complete audio payload, a stream that ended early and a player that never started are different outcomes. Record the relevant observation without extending it into “the customer heard the whole reply.”

For streamed protocols, decide which event or connection the identifier actually covers. A WebSocket can carry multiple speech contexts. Do not label one handshake ID a unique identifier for every later synthesis context unless the current protocol provides that relationship. Preserve the protocol's own context identifiers alongside transport evidence.

Work through a timeout without erasing the first attempt

A fictional venue assistant prepares a reply explaining where to collect a visitor pass. Its application turn is reply-03. Attempt A is submitted with a local client correlation value, but the application times out before seeing a response.

The honest record is that A's final provider result is unknown to the client. The timeout alone does not establish that synthesis never began, no usage was charged or no audio bytes were produced. Save the timeout and the absence of a response ID as separate facts.

Suppose a later, independently authorized retry produces a response with a server request ID. Store it as attempt B under the same turn. Do not replace A with B's successful record. When reviewing duplicate audio, cost or a late first response, you need both attempts to reconstruct what happened.

This distinction matters even when speech itself has no business side effect. Repeating a synthesis may create more generated output or cost. Repeating a tool action such as submitting a booking is a separate, more consequential operation. The client correlation header is not documented here as an idempotency key, so it must not be used as a promise that duplicate submissions will be suppressed.

A robust review also checks what the application did with a late result from A. If B is already the current reply, an old A payload should not suddenly enter playback because it finished later. That is application state handling, separate from the provider's ability to trace either request.

Prepare a support record with only the useful evidence

Before sharing a diagnostic record, verify that it refers to the correct authorized workspace, environment and attempt. A production incident and a local development test can use the same model and similar text. The timestamp alone is a weak way to join them.

The downloadable template asks for:

• UTC start and end times, with the observed error or timeout.
• Endpoint, transport, requested model and client/library version.
• Client correlation value and returned provider ID, each labeled separately.
• Application conversation, turn and attempt references retained internally.
• Whether audio was generated, received, played or still unknown.
• A minimal reproduction description and an internal evidence location.

Do not attach raw request headers, authentication material, signed recording URLs or an entire caller conversation by default. Replace private content with a minimal synthetic phrase where that still explains the issue. If genuine customer evidence is necessary, use the authorized process for that evidence rather than treating an opaque request ID as permission to disclose the underlying conversation.

Inworld provides a support contact in its documentation. This guide prepares a record for review; it does not submit a ticket, guarantee a response time or claim an incident has been resolved. Provider support.

Check cost without assuming a diagnostic allowance

Inspecting existing local records can avoid an unnecessary reproduction request. If a new test is genuinely needed, agree on its scope and funding first. A tracing header is not an allowance for free voice generation.

As checked October 17, Inworld's public On-Demand prices list TTS-2 at USD 25 per million input characters and TTS-2 Flash at USD 15 per million. These are provider model rates, not a Burki bill or an entire conversation price. Paid tiers and agreements can differ. Current provider prices.

At the first illustrative rate, an assumed 10,000 billable characters would cost USD 0.25 for synthesis. That is arithmetic, not an invoice or a test performed here. Inworld's billing documentation describes usage across products and plans; preserve the actual model and account context before reconciling a charge. Billing basis.

Do not infer a failed request's billing outcome from its missing response ID. Keep unknown usage unknown until the relevant account evidence resolves it. Recognition, LLM, platform and carrier charges also belong in a wider voice-agent cost review.

Connect the method to Burki's available evidence

In Burki, open Calls and find the relevant record in Call history. Review the available transcript, captured outcome and action evidence for the reported turn. Retain the actual application call identifier as such; it is not automatically an Inworld server request ID.

The current source has Inworld TTS context and usage handling, while an Inworld STT path separately captures handshake request metadata. That does not prove the TTS wrapper captures the same header or that either value is displayed in the dashboard. A missing UI field should remain a documented evidence gap.

For an AI receptionist, this gives support a clear division of responsibility: identify the application conversation, locate the exact provider attempt where evidence exists, then review the caller's actual outcome separately. The call summary guide covers the application record; request correlation helps locate the provider operation behind it without claiming that correlation alone fixed the call.