> ## Documentation Index > Fetch the complete documentation index at: https://developers.meshapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Query Usage Events > Paginated per-request event history for the authenticated caller. Accepts either a dashboard session token (JWT) or an rsk_ API key; with an API key results are scoped to that single key (body org_id / member filters are ignored). Results are cached for 1 minute per org/filter combination for JWT callers. Pass ?refresh=true to bypass, or filter by `request_id`, which is never served from cache (see below). ## OpenAPI ````yaml /api/openapi.json post /v1/usage/events openapi: 3.1.0 info: title: MeshAPI description: One key, all AI models. version: 0.1.0 servers: - url: https://api.meshapi.ai security: - BearerAuth: [] paths: /v1/usage/events: post: tags: - Usage summary: Query Usage Events description: >- Paginated per-request event history for the authenticated caller. Accepts either a dashboard session token (JWT) or an rsk_ API key; with an API key results are scoped to that single key (body org_id / member filters are ignored). Results are cached for 1 minute per org/filter combination for JWT callers. Pass ?refresh=true to bypass, or filter by `request_id`, which is never served from cache (see below). operationId: query_usage_events parameters: - name: refresh in: query required: false schema: type: boolean default: false title: Refresh - in: header name: X-Mesh-Version required: false schema: type: string enum: - 2026-08 default: 2026-08 example: 2026-08 description: >- Dated version of the API contract to pin this request to. Omit it and the request is served under `2026-08` — the oldest supported version, so an existing integration is never moved by a release. A malformed or unsupported value is rejected with `400 invalid_api_version` rather than falling back silently. The version actually served is echoed as `X-Mesh-Version` on every response, including errors. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UsageFilter' examples: default: summary: Example request value: org_id: 0190a1b2-3c4d-7e8f-9012-3456789abcde since: '2026-07-01' model: - openai/gpt-4o-mini status: - success limit: 20 offset: 0 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UsageEventsPage' examples: default: summary: Example response value: events: - id: 0190a1c0-0000-7000-8000-00000000e1e1 key_id: 0190a1b2-0000-7000-8000-0000000000aa key_label: prod-key user_id: user_01JZ0Q9WZ7ZK3M9YF6R8D2C4B1 end_user_id: customer-42 request_id: req_01ARZ3NDEKTSV4RRFFQ69G5FAV model: openai/gpt-4o-mini model_name: gpt-4o-mini model_provider: openai stream: false prompt_tokens: 128 completion_tokens: 64 total_tokens: 192 cost_usd: '0.0000480' latency_ms: 812 tokens_per_second: 78.82 status: success error_code: null error_category: null error_message: null created_at: '2026-07-14T10:15:30+00:00' model_type: text is_byok: false provider: openai fallback_triggered: false platform_fee_usd: '0.0000024' attempt_no: 1 is_retry_attempt: false routing_fallback: false total: 1284 limit: 50 offset: 0 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - BearerAuth: [] components: schemas: UsageFilter: properties: since: anyOf: - type: string - type: 'null' title: Since until: anyOf: - type: string - type: 'null' title: Until model: anyOf: - items: type: string type: array - type: 'null' title: Model status: anyOf: - items: type: string type: array - type: 'null' title: Status key_id: anyOf: - items: type: string type: array - type: 'null' title: Key Id org_id: type: string title: Org Id team_id: anyOf: - type: string - type: 'null' title: Team Id member_user_id: anyOf: - type: string - type: 'null' title: Member User Id end_user_id: anyOf: - type: string - type: 'null' title: End User Id request_id: anyOf: - type: string - type: 'null' title: Request Id limit: anyOf: - type: integer maximum: 200 minimum: 1 - type: 'null' title: Limit default: 50 offset: anyOf: - type: integer minimum: 0 - type: 'null' title: Offset default: 0 type: object required: - org_id title: UsageFilter UsageEventsPage: properties: events: items: $ref: '#/components/schemas/UsageEventOut' type: array title: Events total: type: integer title: Total limit: type: integer title: Limit offset: type: integer title: Offset type: object required: - events - total - limit - offset title: UsageEventsPage HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError UsageEventOut: properties: id: type: string title: Id key_id: type: string title: Key Id key_label: anyOf: - type: string - type: 'null' title: Key Label user_id: anyOf: - type: string - type: 'null' title: User Id end_user_id: anyOf: - type: string - type: 'null' title: End User Id request_id: type: string title: Request Id model: type: string title: Model model_name: type: string title: Model Name model_provider: anyOf: - type: string - type: 'null' title: Model Provider stream: type: boolean title: Stream prompt_tokens: anyOf: - type: integer - type: 'null' title: Prompt Tokens completion_tokens: anyOf: - type: integer - type: 'null' title: Completion Tokens total_tokens: anyOf: - type: integer - type: 'null' title: Total Tokens cost_usd: anyOf: - type: string - type: 'null' title: Cost Usd latency_ms: anyOf: - type: integer - type: 'null' title: Latency Ms tokens_per_second: anyOf: - type: number - type: 'null' title: Tokens Per Second provider_latency_ms: anyOf: - type: integer - type: 'null' title: Provider Latency Ms platform_latency_ms: anyOf: - type: integer - type: 'null' title: Platform Latency Ms ttft_ms: anyOf: - type: integer - type: 'null' title: Ttft Ms status: type: string title: Status error_code: anyOf: - type: string - type: 'null' title: Error Code error_category: anyOf: - type: string - type: 'null' title: Error Category error_message: anyOf: - type: string - type: 'null' title: Error Message created_at: type: string title: Created At images_generated: anyOf: - type: integer - type: 'null' title: Images Generated model_type: anyOf: - type: string - type: 'null' title: Model Type is_byok: anyOf: - type: boolean - type: 'null' title: Is Byok byok_key_id: anyOf: - type: string - type: 'null' title: Byok Key Id byok_key_label: anyOf: - type: string - type: 'null' title: Byok Key Label provider: anyOf: - type: string - type: 'null' title: Provider fallback_triggered: anyOf: - type: boolean - type: 'null' title: Fallback Triggered platform_fee_usd: anyOf: - type: string - type: 'null' title: Platform Fee Usd image_tokens: anyOf: - type: integer - type: 'null' title: Image Tokens member_name: anyOf: - type: string - type: 'null' title: Member Name member_email: anyOf: - type: string - type: 'null' title: Member Email attempt_no: anyOf: - type: integer - type: 'null' title: Attempt No is_retry_attempt: anyOf: - type: boolean - type: 'null' title: Is Retry Attempt routing_fallback: anyOf: - type: boolean - type: 'null' title: Routing Fallback model_requested: anyOf: - type: string - type: 'null' title: Model Requested type: object required: - id - key_id - key_label - request_id - model - model_name - model_provider - stream - prompt_tokens - completion_tokens - total_tokens - cost_usd - latency_ms - tokens_per_second - status - error_code - created_at title: UsageEventOut 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: BearerAuth: type: http scheme: bearer description: >- Enter your MeshAPI key (`rsk_...`) — sent as `Authorization: Bearer `. ````