Unique identifier for this specific AI audio transaction. Used for deduplication, correlation with request/response pairs, and transaction lookup in Revenium analytics. If not provided, a UUID will be auto-generated. For best practices, generate a UUID in your application before making the AI call and use the same ID when submitting to Revenium. You can use either 'spanId' (recommended) or 'transactionId'.

Optional trace identifier to group multiple related AI audio calls that belong to the same overall user request or workflow. For example, if a single user query triggers multiple AI calls (e.g., transcription + translation), use the same traceId for all calls to analyze them together in Revenium's analytics. Leave null for standalone operations.

The AI model identifier used for this audio operation. Should match the exact model name from your AI provider (e.g., 'whisper-1', 'tts-1-hd', 'gpt-4o-realtime-preview'). This is used for cost calculation, performance analytics, and model comparison reporting in Revenium. Valid model names in Revenium for proper cost estimate can be verified using the sources/ai/models endpoint.

The underlying AI provider/vendor whose model is actually processing the request. This identifies which company's AI model is being used, regardless of how you're accessing it (direct API, proxy, or gateway).

Common values: 'OpenAI' (for Whisper, TTS), 'Anthropic', 'Google', 'AssemblyAI', 'ElevenLabs', 'Deepgram'.

Custom values are accepted but may affect analytics categorization. If using Revenium middleware, this is typically auto-populated from the AI provider's API response.

The timestamp when your application sent the request to the AI provider, in ISO 8601 format with UTC timezone (e.g., '2025-03-02T15:04:05Z'). This is used to calculate request duration and analyze usage patterns over time. Set this to the time immediately before calling the AI provider's API.

The timestamp when the AI audio operation finished, in ISO 8601 format with UTC timezone. For streaming requests, this is when the last data was received and the stream closed. For non-streaming requests, this is when the complete response was received. Used to calculate total request duration.

The type of operation performed

Technical classification of the specific audio operation. Valid values: 'transcription', 'translation', 'synthesis', 'speech', 'tts', 'realtime'. Invalid values will be rejected with HTTP 400. Required for proper billing routing (determines per-second vs per-character vs per-token billing) - missing values are accepted with a warning.

The type of cost being tracked. Currently always 'AI' for AI audio costs. This field is used internally by Revenium to categorize different types of metered usage. You typically do not need to set this field as it defaults to 'AI'.

The name of the subscriber's organization from your system to allow Revenium to track usage & costs by company. i.e. AcmeCorp. If several subscriberIds have the same organizationName, Revenium's reporting will show usage for the entire organization broken down by subscriberId. This field is used for lookup and auto-creation of organizations in Revenium.

Unique identifier of the subscription from your own system that you wish to use to correlate usage between Revenium & your application.

The name of the product from your system that you wish to use to correlate usage between Revenium & your application. This field is used for lookup and auto-creation of products in Revenium.

The AI agent that is making the request

Deployment environment where this AI audio operation was executed. Used for filtering and analyzing usage patterns across different deployment stages. Common values: 'production', 'staging', 'development', 'test'. Leave null if not tracking by environment.

Cloud region or geographic location where this AI audio operation was processed. Used for analyzing latency patterns, compliance requirements, and regional cost differences. Examples: 'us-east-1', 'eu-west-1', 'ap-southeast-2'. Leave null if not tracking by region.

Parent transaction ID for hierarchical tracing. When an AI audio operation is part of a larger workflow or spawned by another AI call, this field references the parent's spanId/transactionId. Used to build transaction trees and understand call hierarchies in complex multi-step AI workflows. Leave null for root-level transactions. You can use either 'parentSpanId' (recommended) or 'parentTransactionId'.

Human-readable name for this transaction. Provides context about what this AI audio operation is doing in business terms. Examples: 'Transcribe Meeting', 'Generate Podcast Intro', 'Translate Customer Call'. Used in trace visualization for better readability. Falls back to taskType if not provided.

Categorical identifier for grouping similar workflows (e.g., 'meeting_transcription', 'podcast_generation'). Enables trace-level analytics and anomaly detection within workflow cohorts. Must contain only alphanumeric characters, hyphens, and underscores. Max 128 characters. Defaults to 'uncategorized' if not provided or invalid. All transactions in the same trace must have the same traceType.

Human-readable label for individual trace instances (e.g., 'Weekly Standup - Week 42'). Enables finding specific workflow executions. Can contain any UTF-8 string. Max 256 characters. All transactions in the same trace must have the same traceName.

Identifier for multi-agent framework team or squad (e.g., ARK, CrewAI). Used to group AI operations by agent team for analytics and cost tracking. Free-form string, max 256 characters.

Human-readable name for the squad type (e.g., 'Loan Processing', 'Document Analysis'). Used for display in the UI and analytics grouping. If squadId is provided without squadName, squadId will be used as the display name.

The agent's role within this squad execution (e.g., 'Document Extractor', 'Credit Checker'). Used to identify the purpose of each agent's contribution to the squad workflow.

Unique identifier for the agentic job instance. Used to correlate all AI operations within a single job execution. Should be unique per job run (e.g., UUID or meaningful ID like 'loan-123-processing').

Human-readable name for the agentic job. Used for display in the UI and analytics grouping. If agenticJobId is provided without agenticJobName, the ID will be used as the display name.

Category or type of the agentic job. Normalized to lowercase on ingest to prevent data fragmentation. Used for grouping jobs by type in analytics and ROI calculations.

Version identifier for the job definition. Used to track job evolution and compare performance across versions.

Error message or reason if the AI audio operation failed. Include this field when the AI provider returns an error (e.g., audio too long, unsupported format, rate limit exceeded, content policy violation). Used for error rate analytics and debugging. Leave null for successful operations.

Identifier of the Revenium middleware package or SDK that captured and submitted this AI audio metadata. This field is AUTOMATICALLY SET by Revenium's middleware packages (e.g., 'revenium-openai-python', 'revenium-assemblyai-node'). You typically should NOT manually set this field. It is used for analytics to track which integration methods are being used and for debugging middleware-specific issues.

The routing or aggregation layer used to access the AI model. This identifies whether you're calling the AI provider directly or through an intermediary service.

Common values: 'DIRECT', 'LITELLM', 'OPENROUTER', 'PORTKEY', or provider names when calling directly.

Custom values are accepted for specialized routing layers or gateways. This field is used for integration tracking and analytics.

Optional category to group related AI tasks for cost and performance analysis. Use consistent values to compare metrics across different models or vendors performing the same type of work. Examples: 'transcription', 'tts', 'translation', 'voice-clone'. This is freeform text - choose values that match your use cases.

Language code (ISO 639-1) for the audio content.

Response format for transcription (e.g., 'verbose_json', 'json', 'text', 'srt', 'vtt'). Note: 'verbose_json' is required to get duration from Whisper. Does not affect pricing.

TTS voice selection (e.g., 'alloy', 'echo', 'fable', 'onyx', 'nova', 'shimmer'). Does not affect pricing.

Source language for translation operations.

Target language for translation operations. For Whisper translate, always 'english'.

Audio format (e.g., 'mp3', 'wav', 'flac', 'opus', 'aac'). Used for analytics and debugging. Does not affect pricing.

Quality setting for TTS (e.g., 'standard', 'hd'). HD quality (tts-1-hd) typically costs 2x standard (tts-1).

Input prompts/messages for this audio operation. JSON-serialized array of messages in the same format as the LLM endpoint. Used for prompt analytics and cost attribution.

Output response content or metadata (e.g., transcription text, generated audio URLs). Used for analytics and audit trail.

How this operation should be billed. For audio: PER_SECOND (Whisper transcription/translation), PER_CHARACTER (TTS), or PER_TOKEN (realtime). Routes cost calculation in backend. Defaults to PER_SECOND if not specified. Use PER_MINUTE with custom pricing dimensions if needed.

Reason why billing was skipped.

Pricing tier for batch discounts. BATCH = 50% discount, STANDARD = normal pricing.

Service tier requested by user (e.g., 'priority', 'default', 'flex').

Actual service tier used for billing. May differ from requested if downgraded.

Optional Stripe-style retry-safety key. If present, the response (status + body) is cached keyed by (tenant, key). Identical retries replay the cached response; body mismatch returns 409 idempotency_key_mismatch; a concurrent in-flight call returns 409 idempotency_key_in_progress with Retry-After: 1. Must be 1-255 printable ASCII characters; UUID v4 recommended. See https://docs.revenium.io/integrations/idempotency for full behavior.