Unique identifier for this specific AI video 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 video calls that belong to the same overall user request or workflow. For example, if a single user query triggers multiple AI calls (e.g., generation + upscale), 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 video operation. Should match the exact model name from your AI provider (e.g., 'gen-3', 'gen-2', 'pika-1.0', 'sora'). 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: 'RunwayML' (for Gen-2/Gen-3), 'Pika', 'OpenAI' (for Sora), 'Luma AI', 'Stability AI'.

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 video operation finished, in ISO 8601 format with UTC timezone. For async/queued jobs, this is when the video was ready for download. For sync 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 video operation. Valid values: 'generation', 'upscale', 'extend', 'edit'. Invalid values will be rejected with HTTP 400. Important for billing: upscale is typically much cheaper than generation - missing values are accepted with a warning.

The type of cost being tracked. Currently always 'AI' for AI video 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 video 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 video 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 video 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 video operation is doing in business terms. Examples: 'Generate Product Video', 'Create Marketing Clip', 'Upscale User Content'. Used in trace visualization for better readability. Falls back to taskType if not provided.

Categorical identifier for grouping similar workflows (e.g., 'marketing_video_generation', 'product_demos'). 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., 'Marketing Video Q4 2025'). 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 video operation failed. Include this field when the AI provider returns an error (e.g., content policy violation, rate limit exceeded, job failed). 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 video metadata. This field is AUTOMATICALLY SET by Revenium's middleware packages (e.g., 'revenium-runway-python', 'revenium-pika-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: 'video-generation', 'marketing-videos', 'product-demos', 'social-content'. This is freeform text - choose values that match your use cases.

Video resolution (e.g., '1920x1080', '4K', 'HD').

Async video job identifier for batch/queued processing. Named videoJobId to distinguish from other async job types (e.g., batch completions, image generation).

Completion status for async operations.

Links this operation to a source transaction (e.g., upscale links to original generation).

Input prompts/messages for this video generation. 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., generated video URLs, dimensions). Used for analytics and audit trail.

How this operation should be billed. For video: PER_SECOND (Google Veo) or CREDITS (RunwayML). Routes cost calculation in backend. Defaults to PER_SECOND if not specified.

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.

Google priority tier: 'best_effort' (-30%), 'on_demand' (base), 'committed' (-20%).