> ## Documentation Index > Fetch the complete documentation index at: https://veniceai-mintlify-d2fddb8a.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # تحليلات استخدام الفوترة (بيتا) > **Beta**: This endpoint is currently in beta and may be unstable. Request/response schemas and behavior may change without notice. Get aggregated usage analytics for the authenticated user with breakdowns by date, model, and API key. This endpoint provides summary views of your API usage, ideal for dashboards and usage monitoring. Data is cached for 10 minutes. هذه endpoint بيتا وقد تكون غير مستقرة أو تتغير دون إشعار. احصل على تحليلات استخدام مُجمَّعة للمستخدم المُصادَق عليه، مع تفصيل حسب التاريخ والنموذج ومفتاح API. توفّر هذه الـ endpoint عروض ملخّصة لبيانات استخدام API لبناء لوحات المعلومات ومراقبة الاستهلاك. يتم تخزين البيانات مؤقتًا لمدة 10 دقائق. ## معاملات الاستعلام يمكنك تحديد الفترة الزمنية للتحليلات باستخدام إما: * **lookback**: فترة نسبية مثل "7d" (7 أيام)، "30d" (30 يومًا)، حتى "90d" (90 يومًا) * **startDate** و **endDate**: نطاق تاريخ مخصص بصيغة `YYYY-MM-DD`. كلاهما مطلوب إذا تم توفير أي منهما. إذا لم يتم تحديد أي معاملات، فإن فترة lookback الافتراضية هي 7 أيام. ## حقول الاستجابة ### lookback فترة lookback المستخدمة في الاستعلام. إما بصيغة "Nd" (مثل "7d") أو بصيغة "startDate:endDate". ### byDate إجماليات الاستخدام اليومية للفترة المطلوبة. * **date**: التاريخ بصيغة `YYYY-MM-DD` * **USD**: إجمالي الاستخدام بالدولار الأمريكي لذلك اليوم * **DIEM**: إجمالي الاستخدام بـ DIEM لذلك اليوم ### byModel تفصيل الاستخدام حسب النموذج، مُرتَّب حسب إجمالي الإنفاق (الأعلى أولًا). * **modelName**: الاسم المعروض للنموذج (مثل "GLM 5") * **unitType**: نوع الوحدات المستهلكة (tokens، images، chars، minutes، seconds) * **modelType**: نوع النموذج (LLM، IMAGE، TTS، ASR، VIDEO)، أو null * **totalUsd**: إجمالي الدولارات المُنفَقة على هذا النموذج * **totalDiem**: إجمالي DIEM المُنفَقة على هذا النموذج * **totalUnits**: إجمالي الوحدات المستهلكة لهذا النموذج * **breakdown**: مصفوفة من تفصيلات الاستخدام حسب النوع (متوفر فقط إذا كانت هناك أنواع متعددة). كل إدخال يحتوي على: * **type**: نوع الـ token (مثل "Input"، "Output"، "Cache Read"، "Cache Write") * **usd**: المبلغ بالدولار لهذا التفصيل * **diem**: المبلغ بـ DIEM لهذا التفصيل * **units**: عدد الوحدات لهذا التفصيل ### byModelDaily بيانات الرسم البياني اليومية لأفضل 8 نماذج. يحتوي كل إدخال على "date" (طابع زمني) بالإضافة إلى أسماء النماذج كمفاتيح مع قيم استخدام DIEM. ### topModels مصفوفة من أسماء أفضل 8 نماذج حسب الاستخدام، لوسائل إيضاح الرسوم البيانية. ### byKey تفصيل الاستخدام حسب مفتاح API، مُرتَّب حسب إجمالي الإنفاق (الأعلى أولًا). * **apiKeyId**: معرّف مفتاح API، أو null إذا كان الاستخدام من تطبيق الويب * **description**: وصف مفتاح API أو "Web App" * **totalUsd**: إجمالي الدولارات المُنفَقة عبر هذا المفتاح * **totalDiem**: إجمالي DIEM المُنفَقة عبر هذا المفتاح * **totalUnits**: إجمالي الوحدات المستهلكة عبر هذا المفتاح ### byKeyDaily بيانات الرسم البياني اليومية لأفضل 8 مفاتيح API. يحتوي كل إدخال على "date" (طابع زمني) بالإضافة إلى أوصاف المفاتيح كمفاتيح مع قيم استخدام DIEM. ### topKeyNames مصفوفة من أوصاف أفضل 8 مفاتيح API حسب الاستخدام، لوسائل إيضاح الرسوم البيانية. ## أمثلة الاستخدام ```bash theme={null} # الحصول على تحليلات الاستخدام لآخر 7 أيام (الافتراضي) curl -X GET "https://api.venice.ai/api/v1/billing/usage-analytics" \ -H "Authorization: Bearer YOUR_API_KEY" # الحصول على تحليلات الاستخدام لآخر 30 يومًا curl -X GET "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=30d" \ -H "Authorization: Bearer YOUR_API_KEY" # الحصول على تحليلات الاستخدام لنطاق تاريخ محدد curl -X GET "https://api.venice.ai/api/v1/billing/usage-analytics?startDate=2024-01-01&endDate=2024-01-31" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## OpenAPI ````yaml GET /billing/usage-analytics openapi: 3.0.0 info: description: The Venice.ai API. termsOfService: https://venice.ai/legal/tos title: Venice.ai API version: '20260622.204854' x-guidance: >- Venice.ai is an OpenAI-compatible inference API supporting text, image, audio, and video generation. **Authentication options:** - API Key: Use Bearer token in Authorization header - x402 Wallet: Use USDC credits via EVM or Solana wallet (no account required) **For x402 wallet access:** 1. POST /x402/top-up without headers to get payment requirements 2. Choose one of the returned Base or Solana payment options and sign a USDC payment using the x402 SDK 3. POST /x402/top-up with PAYMENT-SIGNATURE header to add credits 4. Call any inference endpoint with SIGN-IN-WITH-X header **Pricing:** Prepaid credits consumed per request. Check /models for available models and their capabilities. servers: - url: https://api.venice.ai/api/v1 security: - BearerAuth: [] tags: - description: >- Generate speech/audio, transcribe audio, and manage asynchronous audio generation jobs. name: Audio - description: >- Given a list of messages comprising a conversation, the model will return a response. Supports multimodal inputs including text, images, audio (input_audio), and video (video_url) for compatible models. name: Chat - description: List and describe the various models available in the API. name: Models - description: Generate and manipulate images using AI models. name: Image - description: Generate videos using AI models. name: Video - description: List and retrieve character information for use in completions. name: Characters - description: >- Billing and usage analytics. **Beta**: This API is currently in beta and may be unstable. Endpoints, request/response schemas, and behavior may change without notice. name: Billing - description: Proxy JSON-RPC requests to blockchain nodes. Billed per credit. name: Crypto RPC - description: >- Wallet-based API access using the x402 protocol. No API key required — authenticate with an EVM or Solana wallet. **How it works:** 1. **Authenticate** — Send a `SIGN-IN-WITH-X` header (base64-encoded signed SIWX payload) with any request. EVM wallets sign an EIP-4361 SIWE message; Solana wallets sign the Solana SIWX message with Ed25519. See the `siwx` security scheme for the exact format. 2. **Top up** — `POST /x402/top-up` without a payment header returns an `accepts` array with Base and Solana USDC payment options. Choose one entry, sign it using the x402 SDK (`npm install x402`), and re-submit with the `PAYMENT-SIGNATURE` header (the legacy `X-402-Payment` and `X-PAYMENT` names are also accepted). 3. **Use any endpoint** — All inference endpoints (chat, image, audio, video, embeddings) accept `siwx` as an alternative to `BearerAuth`. Charges are deducted from your USDC credit balance. 4. **Monitor balance** — `GET /x402/balance/{walletAddress}` returns your current balance. The `X-Balance-Remaining` response header on inference calls also reports it. **Quick start (5 lines):** ``` import { VeniceClient } from '@venice-ai/x402-client' const venice = new VeniceClient(process.env.WALLET_KEY) await venice.topUp(10) // $10 USDC on a supported x402 rail const res = await venice.chat({ model: 'zai-org-glm-5-1', messages: [{ role: 'user', content: 'Hello!' }] }) ``` **Payment:** USDC on Base (chain ID 8453) or Solana mainnet. Minimum top-up: $5. Alternatively, stake DIEM tokens for daily credits (1 DIEM = $1/day). name: x402 externalDocs: description: Venice.ai API documentation url: https://docs.venice.ai paths: /billing/usage-analytics: get: tags: - Billing summary: /api/v1/billing/usage-analytics description: >- **Beta**: This endpoint is currently in beta and may be unstable. Request/response schemas and behavior may change without notice. Get aggregated usage analytics for the authenticated user with breakdowns by date, model, and API key. This endpoint provides summary views of your API usage, ideal for dashboards and usage monitoring. Data is cached for 10 minutes. operationId: getBillingUsageAnalytics parameters: - schema: type: string pattern: ^[1-9]\d*d$ default: 7d description: >- Lookback period for usage data. Format: number followed by "d" (e.g., "7d", "30d"). Maximum: 90d example: 7d required: false name: lookback in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Start date for filtering records (YYYY-MM-DD). If provided, endDate is also required. example: '2024-01-01T00:00:00.000Z' required: false name: startDate in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- End date for filtering records (YYYY-MM-DD). If provided, startDate is also required. example: '2024-01-31T00:00:00.000Z' required: false name: endDate in: query responses: '200': description: Successful response with aggregated usage analytics content: application/json: schema: type: object properties: lookback: type: string description: >- The lookback period used for the query. Either "Nd" format or "startDate:endDate" format. example: 7d byDate: type: array items: type: object properties: date: type: string description: Date in YYYY-MM-DD format example: '2024-01-15T00:00:00.000Z' USD: type: number description: Total USD usage for this date DIEM: type: number description: Total DIEM usage for this date required: - date - USD - DIEM description: Daily usage totals for the requested period byModel: type: array items: type: object properties: modelName: type: string description: Display name of the model example: GLM 5.1 unitType: type: string description: >- Type of units (tokens, images, chars, minutes, seconds) example: tokens modelType: type: string nullable: true description: Type of model (LLM, IMAGE, TTS, ASR, VIDEO) example: LLM totalUsd: type: number description: Total USD usage for this model totalDiem: type: number description: Total DIEM usage for this model totalUnits: type: number description: Total units consumed for this model breakdown: type: array items: type: object properties: type: type: string description: >- Token type (e.g., "Input", "Output", "Cache Read", "Cache Write") usd: type: number description: USD amount for this breakdown diem: type: number description: DIEM amount for this breakdown units: type: number description: Number of units for this breakdown required: - type - usd - diem - units description: >- Breakdown by token type (only present if multiple types) required: - modelName - unitType - modelType - totalUsd - totalDiem - totalUnits description: >- Usage breakdown by model, sorted by total spend (highest first) byModelDaily: type: array items: type: object additionalProperties: type: number description: >- Daily chart data for top 8 models. Each entry has "date" (timestamp) plus model names as keys. topModels: type: array items: type: string description: Names of the top 8 models by usage (for chart legends) byKey: type: array items: type: object properties: apiKeyId: type: string nullable: true description: API key ID, or null if usage was from web app description: type: string description: API key description or "Web App" example: My Production Key totalUsd: type: number description: Total USD usage for this key totalDiem: type: number description: Total DIEM usage for this key totalUnits: type: number description: Total units consumed for this key required: - apiKeyId - description - totalUsd - totalDiem - totalUnits description: >- Usage breakdown by API key, sorted by total spend (highest first) byKeyDaily: type: array items: type: object additionalProperties: type: number description: >- Daily chart data for top 8 API keys. Each entry has "date" (timestamp) plus key descriptions as keys. topKeyNames: type: array items: type: string description: >- Descriptions of the top 8 API keys by usage (for chart legends) required: - lookback - byDate - byModel - byModelDaily - topModels - byKey - byKeyDaily - topKeyNames additionalProperties: false description: >- Aggregated usage analytics response with breakdowns by date, model, and API key example: lookback: 7d byDate: - date: '2024-01-15T00:00:00.000Z' USD: 0.5 DIEM: 10.25 - date: '2024-01-14T00:00:00.000Z' USD: 0.3 DIEM: 8.75 byModel: - modelName: GLM 5.1 unitType: tokens modelType: LLM totalUsd: 0.4 totalDiem: 12.5 totalUnits: 50000 breakdown: - type: Output usd: 0.3 diem: 10 units: 35000 - type: Input usd: 0.1 diem: 2.5 units: 15000 byModelDaily: - date: 1705276800000 GLM 5.1: 5.5 Kimi K2.6: 3.2 topModels: - GLM 5.1 - Kimi K2.6 byKey: - apiKeyId: key_abc123 description: Production Key totalUsd: 0.8 totalDiem: 15 totalUnits: 75000 - apiKeyId: null description: Web App totalUsd: 0 totalDiem: 4 totalUnits: 25000 byKeyDaily: - date: 1705276800000 Production Key: 8.5 Web App: 2 topKeyNames: - Production Key - Web App '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/DetailedError' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/StandardError' '500': description: Inference processing failed content: application/json: schema: $ref: '#/components/schemas/StandardError' '504': description: Query timed out - try reducing the lookback period content: application/json: schema: properties: error: description: Error message indicating query timeout type: string type: object components: schemas: DetailedError: type: object properties: details: type: object properties: {} description: Details about the incorrect input example: _errors: [] field: _errors: - Field is required error: type: string description: A description of the error required: - error StandardError: type: object properties: error: type: string description: A description of the error required: - error securitySchemes: BearerAuth: bearerFormat: JWT scheme: bearer type: http ````