> ## Documentation Index > Fetch the complete documentation index at: https://docs.mobula.io/llms.txt > Use this file to discover all available pages before exploring further. # Get API & WebSocket Usage > A single API key's consumption over a time window — REST usage (source=api) or WebSocket usage (source=wss) — with per-endpoint / per-event breakdown, totals, and cursor pagination. Choose one `source` per call: * **`api`** — REST usage: `credits`, `requestCalls`, and per-endpoint `metrics`. * **`wss`** — WebSocket usage: `events`, with a per-service `breakdown`. Provide `apiKey` and exactly one of `customerId` or `organizationId` — find these on your [dashboard settings page](https://admin.mobula.io). Rows are newest-first — paginate with `nextCursor`. ## OpenAPI ````yaml get /2/usage openapi: 3.0.0 info: version: 1.0.0 title: Mobula API description: >- Documentation of the Mobula API **Demo API**: The default server (demo-api.mobula.io) is a demo API with rate limits. For production use, please use api.mobula.io with an API key from https://admin.mobula.io servers: - url: https://demo-api.mobula.io/api/ description: Demo API (rate limited, for testing only) - url: https://api.mobula.io/api/ description: Production API (requires API key) security: [] tags: - name: V2 - Token description: Token details, price, security, ATH, and holder data - name: V2 - Market Data description: Market details, OHLCV history, and lighthouse metrics - name: V2 - Trades description: Token trades, enriched trades, and trade filters - name: V2 - Wallet description: Wallet positions, activity, trades, analysis, and labels - name: V2 - Assets description: Cross-chain asset details and price history - name: V2 - Swap description: Swap quoting and execution - name: V2 - Perps description: Perpetual futures quoting, execution, and positions - name: V2 - Bridge description: Cross-chain bridge quoting and intent status (Alpha Preview) - name: V2 - DeFi description: Bonding pools and pulse data - name: V2 - Search description: Universal fast search - name: V2 - Usage description: Per-key API and WebSocket usage history - name: V2 - Blockchains description: System metadata and chain listings - name: V2 - Prediction Markets description: >- Polymarket markets/events, wallet positions, and the full execution stack (auth, order build/submit/cancel, approvals, pUSD wrap/unwrap, deploy, deposit/withdraw, redeem). Alpha — see /api/2/pm/*. - name: V1 - Market Data description: Market prices, history, sparklines, pairs, and multi-data - name: V1 - Wallet description: Wallet portfolio, transactions, history, and NFTs - name: V1 - Token description: First buyers - name: V1 - Trades description: Market trades by pair - name: V1 - Metadata description: Token metadata, categories, trendings, and news - name: V1 - Assets description: List all assets - name: V1 - Search description: Search for assets, tokens, and pairs - name: V1 - DeFi description: Bonding pool pulse data - name: V1 - Blockchains description: Blockchain listings, pairs, and stats - name: V1 - Webhooks description: Webhook management - name: V1 - Feed description: Custom feed creation paths: /2/usage: get: tags: - V2 - Usage summary: Get API & WebSocket usage description: >- Returns a single API key's consumption over a from/to window — REST usage (`source=api`) or WebSocket usage (`source=wss`); one source per call. Hourly rows with a per-endpoint / per-event breakdown, grand totals, and cursor pagination (newest-first). Ownership is verified against the provided `customerId` or `organizationId`. Usage is aggregated hourly and available for the last 12 months. parameters: - schema: type: string enum: - api - wss description: >- Which usage stream to return: `api` (REST credits/calls) or `wss` (websocket/webhook events). Required; only one per call. example: api required: true description: >- `api` (REST credits/calls) or `wss` (WebSocket/webhook events). One per call. name: source in: query - schema: type: string minLength: 1 description: >- API key to return usage for. Find your keys on the dashboard settings page (admin.mobula.io). required: true description: >- API key to return usage for. Find your keys on the dashboard settings page (admin.mobula.io). name: apiKey in: query - schema: type: string minLength: 1 description: >- Verify the key belongs to this customer. Provide exactly one of customerId or organizationId. required: false description: >- Verify the key belongs to this customer. Provide exactly one of customerId or organizationId. name: customerId in: query - schema: type: string minLength: 1 description: >- Verify the key belongs to this organization. Mutually exclusive with customerId. required: false description: >- Verify the key belongs to this organization. Mutually exclusive with customerId. name: organizationId in: query - schema: anyOf: - type: integer nullable: true - type: string nullable: true - nullable: true description: >- Window start — epoch ms or ISO 8601. Defaults to `to` minus 30 days; must be within the last 12 months. required: false description: >- Window start — epoch ms or ISO 8601. Defaults to `to` minus 30 days; must be within the last 12 months. name: from in: query - schema: anyOf: - type: integer nullable: true - type: string nullable: true - nullable: true description: >- Window end — epoch ms or ISO 8601. Defaults to now; future values clamped to now. required: false description: >- Window end — epoch ms or ISO 8601. Defaults to now; future values clamped to now. name: to in: query - schema: type: integer description: Page size for `rows` (1–100, default 20). required: false name: limit in: query - schema: type: string description: >- Pagination cursor from a previous `nextCursor`. Rows are newest-first. required: false name: cursor in: query responses: '200': description: Usage response. content: application/json: schema: $ref: '#/components/schemas/UsageResponse' '400': description: Invalid params, or a window older than 12 months. content: application/json: schema: $ref: '#/components/schemas/UsageError' '403': description: >- The apiKey doesn't belong to the provided customerId / organizationId. content: application/json: schema: $ref: '#/components/schemas/UsageError' '404': description: Unknown or revoked apiKey. content: application/json: schema: $ref: '#/components/schemas/UsageError' components: schemas: UsageResponse: type: object properties: success: type: boolean enum: - true description: 'True on success. Errors return `{ success: false, error }`.' data: $ref: '#/components/schemas/UsageData' required: - success - data UsageError: type: object properties: success: type: boolean enum: - false error: type: string description: Human-readable error message. required: - success - error UsageData: oneOf: - $ref: '#/components/schemas/UsageApiData' - $ref: '#/components/schemas/UsageWssData' discriminator: propertyName: source mapping: api: $ref: '#/components/schemas/UsageApiData' wss: $ref: '#/components/schemas/UsageWssData' UsageApiData: type: object properties: source: type: string enum: - api apiKey: type: string description: Masked API key the usage was computed for (e.g. `00000000...0000`). from: type: string description: Effective window start, ISO 8601. to: type: string description: Effective window end, ISO 8601. finalizedThrough: type: string description: >- Data is complete only up to this timestamp; more recent usage may not be included yet. nextCursor: type: string nullable: true description: >- Pass as `cursor` to fetch the next (older) page of `rows`. Null when no more rows. totals: $ref: '#/components/schemas/UsageApiTotals' rows: type: array items: $ref: '#/components/schemas/UsageApiRow' description: Paginated raw hourly rows, newest first. required: - source - apiKey - from - to - finalizedThrough - nextCursor - totals - rows UsageWssData: type: object properties: source: type: string enum: - wss apiKey: type: string description: Masked API key the usage was computed for (e.g. `00000000...0000`). from: type: string description: Effective window start, ISO 8601. to: type: string description: Effective window end, ISO 8601. finalizedThrough: type: string description: >- Data is complete only up to this timestamp; more recent usage may not be included yet. nextCursor: type: string nullable: true description: >- Pass as `cursor` to fetch the next (older) page of `rows`. Null when no more rows. totals: $ref: '#/components/schemas/UsageWssTotals' rows: type: array items: $ref: '#/components/schemas/UsageWssRow' description: Paginated raw hourly rows, newest first. required: - source - apiKey - from - to - finalizedThrough - nextCursor - totals - rows UsageApiTotals: type: object properties: credits: type: integer minimum: 0 description: Σ api_history.total_calls over the window. requestCalls: type: integer minimum: 0 description: Σ api_history.request_calls over the window. required: - credits - requestCalls UsageApiRow: type: object properties: timestamp: type: string description: Row timestamp (top of the hour), ISO 8601. credits: type: integer minimum: 0 description: Credit-weighted cost in the hour. requestCalls: type: integer minimum: 0 description: Raw request calls in the hour. metrics: type: object additionalProperties: type: number description: >- Per-endpoint breakdown for the hour, as stored: `` → credit cost, `:calls` → raw call count. required: - timestamp - credits - requestCalls - metrics UsageWssTotals: type: object properties: events: type: integer minimum: 0 description: Σ streams_usage.totalevents over the window. required: - events UsageWssRow: type: object properties: timestamp: type: string description: Row timestamp (top of the hour), ISO 8601. events: type: integer minimum: 0 description: Total events across all services in the hour. breakdown: type: array items: $ref: '#/components/schemas/UsageWssBreakdown' description: Per service/type/tag split within the hour. required: - timestamp - events - breakdown UsageWssBreakdown: type: object properties: service: type: string description: Stream service (gateway, multiEvents, aggregatedFeed, streams). type: type: string description: Delivery type (websocket, webhook). tag: type: string description: Optional subscription tag (empty string when none). events: type: integer minimum: 0 description: Events delivered for this service/type/tag. metrics: type: object additionalProperties: type: number description: >- Per-event-type counts, as stored (e.g. `new-token`, `update-token`, `sync`). required: - service - type - tag - events - metrics ````