> ## Documentation Index > Fetch the complete documentation index at: https://docs.airmux.ai/llms.txt > Use this file to discover all available pages before exploring further. # Ingest Usage Events > Ingest up to 1,000 usage events, skipping unauthorized or semantically invalid events. Required permission: `usage.ingest`. ## OpenAPI ````yaml /lib/api-spec/openapi.yaml post /api/v1/events openapi: 3.1.0 info: title: airmux Control Plane API description: > Manage airmux organizations, workspaces, management keys, provider credentials, and data-plane synchronization. Organization and workspace targets are part of each URL. Successful responses wrap their result in `{"data": ...}`. Authenticate with a control-plane management key or a browser session as documented by each operation. Inference keys authenticate model requests at the data plane and are not accepted here. version: 0.1.0 servers: [] security: [] tags: - name: Auth description: Sign in human users, manage browser sessions, and authorize the CLI x-displayName: Authentication - name: Enrollment description: List a user's organizations and create their personal organization - name: Instance Organizations description: List and create organizations on this airmux instance x-displayName: Organizations - name: Instance Users description: Manage human users and service accounts across the instance x-displayName: Users - name: Instance Management Keys description: >- List management keys across the instance, issue instance-scoped credentials, and revoke keys x-displayName: Management Keys - name: Instance Model Catalog description: Manage the providers and models available through this airmux instance x-displayName: Model Catalog - name: Instance Provider Credentials description: Manage provider API keys available across the airmux instance x-displayName: Provider Credentials - name: Data Plane Instances description: Inspect connected data-plane instances x-displayName: Data Planes - name: Instance Activity description: Inspect recent audited changes across the instance x-displayName: Activity - name: OSS description: Bootstrap a new self-hosted airmux deployment x-displayName: Self-hosting - name: Organization Settings description: View, update, and delete one organization x-displayName: Settings - name: Organization Members description: Manage organization membership and organization roles x-displayName: Members - name: Organization Service Accounts description: >- Create and delete organization-managed machine principals and their initial management credentials x-displayName: Service Accounts - name: Organization Invitations description: Invite human users to an organization and optionally one workspace x-displayName: Invitations - name: Organization Workspaces description: List and create workspaces within an organization x-displayName: Workspaces - name: Organization Management Keys description: >- List management keys within an organization, issue organization-scoped credentials, and revoke keys x-displayName: Management Keys - name: Organization Provider Credentials description: Manage provider API keys available across an organization x-displayName: Provider Credentials - name: Organization Usage Events description: Inspect usage events across an organization x-displayName: Usage Events - name: Organization Reports description: Explore usage and requests across an organization or one workspace x-displayName: Reports - name: Organization Activity description: Inspect recent audited changes in an organization x-displayName: Activity - name: Organization Model Catalog description: Inspect the provider and model catalog available to an organization x-displayName: Model Catalog - name: Workspace Settings description: View, update, and delete one workspace x-displayName: Settings - name: Workspace Policies description: Manage workspace inference restrictions and fallbacks x-displayName: Policies - name: Workspace Members description: Manage workspace membership and workspace roles x-displayName: Members - name: Workspace Management Keys description: List and issue management keys scoped to a workspace and revoke keys x-displayName: Management Keys - name: Workspace Playground description: Create and end short-lived browser sessions for playground model requests x-displayName: Playground - name: Workspace Inference Keys description: Issue and revoke credentials for model requests to a workspace x-displayName: Inference Keys - name: Workspace Provider Credentials description: Manage provider API keys available to one workspace x-displayName: Provider Credentials - name: Workspace Usage Events description: Inspect usage events for one workspace x-displayName: Usage Events - name: Workspace Model Catalog description: Inspect the provider and model catalog available to a workspace x-displayName: Model Catalog - name: Data Plane API description: Poll bundles, ingest usage events, and record data-plane heartbeats x-displayName: Synchronization paths: /api/v1/events: post: tags: - Data Plane API summary: Ingest Usage Events description: >- Ingest up to 1,000 usage events, skipping unauthorized or semantically invalid events. Required permission: `usage.ingest`. operationId: ingest_events requestBody: content: application/json: schema: items: oneOf: - $ref: '#/components/schemas/DeniedUsageEventV1' - $ref: '#/components/schemas/RoutedUsageEventV1' discriminator: propertyName: status mapping: denied: $ref: '#/components/schemas/DeniedUsageEventV1' ok: $ref: '#/components/schemas/RoutedUsageEventV1' upstream_error: $ref: '#/components/schemas/RoutedUsageEventV1' timeout: $ref: '#/components/schemas/RoutedUsageEventV1' cancelled: $ref: '#/components/schemas/RoutedUsageEventV1' credential_rejected: $ref: '#/components/schemas/RoutedUsageEventV1' rate_limited: $ref: '#/components/schemas/RoutedUsageEventV1' type: array maxItems: 1000 title: Payloads required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Envelope_EventsIngestedOut_' '401': description: Authentication failed '403': description: The credential does not have the required permission '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - ManagementKey: [] - SessionCookie: [] components: schemas: DeniedUsageEventV1: properties: schema_version: type: integer const: 1 title: Schema Version description: Usage event schema version default: 1 event_id: type: string format: uuid title: Event Id description: Idempotency key for event ingestion request_id: type: string format: uuid title: Request Id description: Data-plane request ID request_started_at: type: string format: date-time title: Request Started At description: Timestamp when the logical request began attempt_started_at: type: 'null' title: Attempt Started At description: No provider attempt was made occurred_at: type: string format: date-time title: Occurred At description: Timestamp when the attempt or denial completed org_id: type: string format: uuid title: Org Id description: Organization that made the request workspace_id: type: string format: uuid title: Workspace Id description: Workspace that made the request key_id: type: string maxLength: 255 minLength: 1 title: Key Id description: Caller credential ID used for the request request_source: type: string enum: - inference_key - playground title: Request Source description: >- Whether the request came from an inference key or a Playground session user_id: type: string format: uuid title: User Id description: Principal that owned the caller credential when the request was made requested_model_id: type: string maxLength: 255 minLength: 1 title: Requested Model Id description: Original caller-requested model before routing and fallback requested_capabilities: items: type: string enum: - tools - reasoning - structured_output type: array uniqueItems: true title: Requested Capabilities description: Original request capabilities before reconciliation model_id: type: string maxLength: 255 minLength: 1 title: Model Id description: Caller-facing model ID provider_id: type: string const: '' title: Provider Id description: No provider was selected before denial default: '' bundle_id: type: string format: uuid title: Bundle Id description: Policy bundle used for the request input_tokens: type: integer maximum: 2147483647 minimum: 0 title: Input Tokens description: Total input tokens output_tokens: type: integer maximum: 2147483647 minimum: 0 title: Output Tokens description: Total output tokens cost_usd: type: string pattern: ^\d+(?:\.\d+)?$ title: Cost Usd description: Total estimated cost in USD cost_input_usd: type: string pattern: ^\d+(?:\.\d+)?$ title: Cost Input Usd description: Estimated input cost in USD default: '0' cost_output_usd: type: string pattern: ^\d+(?:\.\d+)?$ title: Cost Output Usd description: Estimated output cost in USD default: '0' max_output_tokens: anyOf: - type: integer maximum: 2147483647 minimum: 1 - type: 'null' title: Max Output Tokens description: Effective upstream output-token limit cache_read_tokens: type: integer maximum: 2147483647 minimum: 0 title: Cache Read Tokens description: Input tokens read from a provider cache default: 0 cache_write_tokens: type: integer maximum: 2147483647 minimum: 0 title: Cache Write Tokens description: Input tokens written to a provider cache default: 0 latency_ms: type: integer maximum: 2147483647 minimum: 0 title: Latency Ms description: >- Gateway latency in milliseconds: per attempt when routed, end-to-end for a denial before routing status: type: string const: denied title: Status description: The request was denied before routing default: denied stream: type: boolean title: Stream description: Whether the response was streamed credential_id: type: 'null' title: Credential Id description: No provider credential was selected before denial credential_scope: type: 'null' title: Credential Scope description: No provider credential scope was selected before denial token_usage_source: type: string const: not_applicable title: Token Usage Source description: No upstream token usage for a request denied before routing additionalProperties: false type: object required: - event_id - request_id - request_started_at - occurred_at - org_id - workspace_id - key_id - request_source - user_id - requested_model_id - requested_capabilities - model_id - bundle_id - input_tokens - output_tokens - cost_usd - max_output_tokens - latency_ms - stream - token_usage_source title: DeniedUsageEventV1 RoutedUsageEventV1: properties: schema_version: type: integer const: 1 title: Schema Version description: Usage event schema version default: 1 event_id: type: string format: uuid title: Event Id description: Idempotency key for event ingestion request_id: type: string format: uuid title: Request Id description: Data-plane request ID request_started_at: type: string format: date-time title: Request Started At description: Timestamp when the logical request began attempt_started_at: type: string format: date-time title: Attempt Started At description: Timestamp when the provider attempt began occurred_at: type: string format: date-time title: Occurred At description: Timestamp when the attempt or denial completed org_id: type: string format: uuid title: Org Id description: Organization that made the request workspace_id: type: string format: uuid title: Workspace Id description: Workspace that made the request key_id: type: string maxLength: 255 minLength: 1 title: Key Id description: Caller credential ID used for the request request_source: type: string enum: - inference_key - playground title: Request Source description: >- Whether the request came from an inference key or a Playground session user_id: type: string format: uuid title: User Id description: Principal that owned the caller credential when the request was made requested_model_id: type: string maxLength: 255 minLength: 1 title: Requested Model Id description: Original caller-requested model before routing and fallback requested_capabilities: items: type: string enum: - tools - reasoning - structured_output type: array uniqueItems: true title: Requested Capabilities description: Original request capabilities before reconciliation model_id: type: string maxLength: 255 minLength: 1 title: Model Id description: Caller-facing model ID provider_id: type: string maxLength: 63 minLength: 1 title: Provider Id description: Provider that served the request bundle_id: type: string format: uuid title: Bundle Id description: Policy bundle used for the request input_tokens: type: integer maximum: 2147483647 minimum: 0 title: Input Tokens description: Total input tokens output_tokens: type: integer maximum: 2147483647 minimum: 0 title: Output Tokens description: Total output tokens cost_usd: type: string pattern: ^\d+(?:\.\d+)?$ title: Cost Usd description: Total estimated cost in USD cost_input_usd: type: string pattern: ^\d+(?:\.\d+)?$ title: Cost Input Usd description: Estimated input cost in USD default: '0' cost_output_usd: type: string pattern: ^\d+(?:\.\d+)?$ title: Cost Output Usd description: Estimated output cost in USD default: '0' max_output_tokens: anyOf: - type: integer maximum: 2147483647 minimum: 1 - type: 'null' title: Max Output Tokens description: Effective upstream output-token limit cache_read_tokens: type: integer maximum: 2147483647 minimum: 0 title: Cache Read Tokens description: Input tokens read from a provider cache default: 0 cache_write_tokens: type: integer maximum: 2147483647 minimum: 0 title: Cache Write Tokens description: Input tokens written to a provider cache default: 0 latency_ms: type: integer maximum: 2147483647 minimum: 0 title: Latency Ms description: >- Gateway latency in milliseconds: per attempt when routed, end-to-end for a denial before routing status: type: string enum: - ok - upstream_error - timeout - cancelled - credential_rejected - rate_limited title: Status description: How the routed request ended stream: type: boolean title: Stream description: Whether the response was streamed credential_id: type: string format: uuid title: Credential Id description: Provider credential used for the request credential_scope: type: string enum: - platform - org - workspace title: Credential Scope description: Scope of the provider credential used for the request token_usage_source: type: string enum: - provider - estimated title: Token Usage Source description: >- provider: counts accepted from upstream; estimated: gateway estimation was needed, possibly retaining partial provider counts. Independent of catalog-priced cost estimates additionalProperties: false type: object required: - event_id - request_id - request_started_at - attempt_started_at - occurred_at - org_id - workspace_id - key_id - request_source - user_id - requested_model_id - requested_capabilities - model_id - provider_id - bundle_id - input_tokens - output_tokens - cost_usd - max_output_tokens - latency_ms - status - stream - credential_id - credential_scope - token_usage_source title: RoutedUsageEventV1 Envelope_EventsIngestedOut_: properties: data: $ref: '#/components/schemas/EventsIngestedOut' type: object required: - data title: Envelope[EventsIngestedOut] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError EventsIngestedOut: properties: received: type: integer title: Received ingested: type: integer title: Ingested rejected: type: integer title: Rejected type: object required: - received - ingested - rejected title: EventsIngestedOut ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: ManagementKey: type: http description: >- A control-plane management key using the `sk-cp-` prefix. Inference keys are not accepted by control-plane endpoints. scheme: bearer SessionCookie: type: apiKey in: cookie name: airmux_session description: >- Browser session cookie returned by login or signup. Browser requests must also send `X-Requested-With`. ````