> ## Documentation Index > Fetch the complete documentation index at: https://docs.alura.io/llms.txt > Use this file to discover all available pages before exploring further. # Usage > The workspace's plan, this month's API credits (allowance, used, remaining), the daily ceiling, the request rate, today's fetch caps, credits spent by operation and by client, the price of every operation and the upgrade link. Free. Cost: free. ## OpenAPI ````yaml /openapi.json get /v1/usage openapi: 3.1.0 info: title: Alura API version: 1.0.0 description: Etsy market research for scripts and AI assistants. servers: - url: https://api.alura.io security: - apiKey: [] paths: /v1/usage: get: summary: Usage description: >- The workspace's plan, this month's API credits (allowance, used, remaining), the daily ceiling, the request rate, today's fetch caps, credits spent by operation and by client, the price of every operation and the upgrade link. Free. Cost: free. operationId: account.usage.get parameters: - name: fields in: query required: false description: >- Comma-separated dotted paths to return; `id`, `object` and `as_of` always come back. schema: type: string responses: '200': description: OK headers: Request-Id: $ref: '#/components/headers/Request-Id' Alura-Credits-Cost: $ref: '#/components/headers/Alura-Credits-Cost' Alura-Credits-Remaining: $ref: '#/components/headers/Alura-Credits-Remaining' content: application/json: schema: type: object properties: object: type: string const: usage plan: type: string enum: - free - basic - growth - professional period: type: object properties: start: type: string end: type: string required: - start - end additionalProperties: false description: >- The UTC calendar month the API credits belong to; they reset at `end`. credits: type: object properties: allowance: type: integer minimum: 0 description: >- This month's API credits on the current plan; a mid-month upgrade applies at once. used: type: integer minimum: 0 description: >- Spent this month, plus credits held by calls still running (they count against the limit too). remaining: type: integer minimum: 0 required: - allowance - used - remaining additionalProperties: false daily: anyOf: - type: object properties: limit: type: integer minimum: 0 used: type: integer minimum: 0 resets_at: type: string description: The next UTC midnight. required: - limit - used - resets_at additionalProperties: false - type: 'null' description: >- The daily ceiling: 25% of the month on paid plans. null when the plan has none (Free can spend the month in one day). rate_limit: type: object properties: requests_per_minute: type: integer minimum: 0 description: Per API key and per workspace. required: - requests_per_minute additionalProperties: false fetch_caps: type: object properties: shops: type: object properties: limit: type: integer minimum: 0 used: type: integer minimum: 0 required: - limit - used additionalProperties: false products: type: object properties: limit: type: integer minimum: 0 used: type: integer minimum: 0 required: - limit - used additionalProperties: false keywords: type: object properties: limit: type: integer minimum: 0 used: type: integer minimum: 0 required: - limit - used additionalProperties: false shop_names: type: object properties: limit: type: integer minimum: 0 used: type: integer minimum: 0 required: - limit - used additionalProperties: false required: - shops - products - keywords - shop_names additionalProperties: false description: >- Today's (UTC) fetches of items Alura had not seen yet, per type, and the shop-name lookups (spec ยง6). by_operation: type: object propertyNames: type: string additionalProperties: type: integer minimum: 0 description: >- API credits spent this month, by operation id (the keys of `costs`). by_client: type: object propertyNames: type: string additionalProperties: type: integer minimum: 0 description: >- API credits spent this month, by client: `claude`, `chatgpt`, `cursor`, `script`, `other`; `unknown` for charges whose client was not recorded. costs: type: object propertyNames: type: string additionalProperties: type: object properties: credits: type: integer minimum: 0 unit: type: string enum: - call - page - item required: - credits - unit additionalProperties: false description: >- The price of every operation, by operation id: credits per call, per non-empty page or per item returned. upgrade_url: type: string required: - object - plan - period - credits - daily - rate_limit - fetch_caps - by_operation - by_client - costs - upgrade_url additionalProperties: false example: object: usage plan: growth period: start: '2026-10-01T00:00:00.000Z' end: '2026-11-01T00:00:00.000Z' credits: allowance: 20000 used: 3420 remaining: 16580 daily: limit: 5000 used: 210 resets_at: '2026-10-16T00:00:00.000Z' rate_limit: requests_per_minute: 120 fetch_caps: shops: limit: 50 used: 2 products: limit: 500 used: 14 keywords: limit: 500 used: 0 shop_names: limit: 25 used: 1 by_operation: research.products.get: 520 by_client: claude: 400 script: 120 costs: reference.categories.search: credits: 0 unit: call reference.categories.get: credits: 0 unit: call reference.languages.list: credits: 0 unit: call account.me.get: credits: 0 unit: call account.workspaces.list: credits: 0 unit: call account.workspace.switch: credits: 0 unit: call account.usage.get: credits: 0 unit: call account.usage.byDay: credits: 0 unit: call account.usage.events: credits: 0 unit: call research.products.get: credits: 1 unit: call research.products.getMany: credits: 1 unit: item research.products.search: credits: 10 unit: page research.products.similar: credits: 10 unit: page research.shops.get: credits: 1 unit: call research.shops.search: credits: 10 unit: page research.shops.products: credits: 1 unit: page research.keywords.lookup: credits: 1 unit: item research.keywords.get: credits: 1 unit: call research.products.tags: credits: 1 unit: page research.keywords.related: credits: 1 unit: page research.keywords.products: credits: 10 unit: page research.keywords.shops: credits: 10 unit: page research.keywords.history: credits: 1 unit: call research.keywords.trending: credits: 10 unit: page research.products.trending: credits: 10 unit: page research.shops.trending: credits: 10 unit: page research.shops.reviews: credits: 1 unit: page research.products.reviews: credits: 1 unit: page research.products.history: credits: 1 unit: call research.shops.history: credits: 1 unit: call research.lookup: credits: 1 unit: call research.saved.folders.list: credits: 0 unit: call research.saved.folders.get: credits: 0 unit: call research.saved.folders.create: credits: 0 unit: call research.saved.folders.update: credits: 0 unit: call research.saved.folders.delete: credits: 0 unit: call research.saved.lists.list: credits: 0 unit: call research.saved.lists.get: credits: 0 unit: call research.saved.lists.create: credits: 0 unit: call research.saved.lists.update: credits: 0 unit: call research.saved.lists.delete: credits: 0 unit: call research.saved.items.list: credits: 1 unit: item research.saved.items.add: credits: 0 unit: call research.saved.items.remove: credits: 0 unit: call upgrade_url: https://platform.alura.io/settings/billing '400': $ref: '#/components/responses/Problem400' '401': $ref: '#/components/responses/Problem401' '402': $ref: '#/components/responses/Problem402' '403': $ref: '#/components/responses/Problem403' '404': $ref: '#/components/responses/Problem404' '405': $ref: '#/components/responses/Problem405' '429': $ref: '#/components/responses/Problem429' '500': $ref: '#/components/responses/Problem500' '503': $ref: '#/components/responses/Problem503' x-codeSamples: - lang: bash label: cURL source: |- curl "https://api.alura.io/v1/usage" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: |- const res = await fetch('https://api.alura.io/v1/usage', { headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}`, }, }); console.log(await res.json()); - lang: python label: Python source: |- import json import os import urllib.request request = urllib.request.Request( "https://api.alura.io/v1/usage", headers={ "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}", }, ) with urllib.request.urlopen(request) as response: print(json.load(response)) components: headers: Request-Id: description: '`req_` + ULID; quote it when reporting a problem.' schema: type: string Alura-Credits-Cost: description: API credits this call cost. schema: type: integer Alura-Credits-Remaining: description: >- API credits left in the workspace's monthly allowance, counting calls still in flight. Absent when it cannot be read right now. schema: type: integer responses: Problem400: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/invalid_request title: Invalid request status: 400 code: invalid_request detail: Invalid request suggestion: Fix the request as the detail says, then send it again. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem401: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/unauthorized title: Unauthorized status: 401 code: unauthorized detail: Unauthorized suggestion: 'Send a valid API key as `Authorization: Bearer alura_sk_...`.' retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem402: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/credits_exhausted title: API credits exhausted status: 402 code: credits_exhausted detail: API credits exhausted suggestion: Upgrade the plan or wait for the monthly reset. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem403: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/plan_required title: Plan required status: 403 code: plan_required detail: Plan required suggestion: Upgrade the workspace plan to use this operation. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem404: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/not_found title: Not found status: 404 code: not_found detail: Not found suggestion: Check the ID, or search for it first. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem405: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/method_not_allowed title: Method not allowed status: 405 code: method_not_allowed detail: Method not allowed suggestion: Use one of the methods in the Allow header. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem429: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/rate_limited title: Rate limited status: 429 code: rate_limited detail: Rate limited suggestion: Wait for Retry-After, then retry. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem500: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/internal_error title: Internal error status: 500 code: internal_error detail: Internal error suggestion: Retry; if it keeps failing, report the request_id. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem503: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/credits_unavailable title: API credits unavailable status: 503 code: credits_unavailable detail: API credits unavailable suggestion: Retry shortly. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B schemas: Problem: type: object description: RFC 9457 problem details. properties: type: type: string format: uri title: type: string status: type: integer code: type: string description: A code from the error catalog; new codes may be added. x-extensible-enum: - invalid_request - unknown_parameter - invalid_cursor - cursor_window_exceeded - id_type_mismatch - invalid_keyword - unauthorized - credits_exhausted - plan_required - insufficient_scope - workspace_required - workspace_locked - browser_refused - role_required - impersonation_refused - recent_sign_in_required - not_found - not_found_on_etsy - shop_opted_out - method_not_allowed - conflict - key_limit_reached - idempotency_processing - unprocessable - rate_limited - throttled - daily_credit_cap_exceeded - credits_reserved - fetch_limit_reached - internal_error - upstream_unavailable - credits_unavailable - service_unavailable - fetch_unavailable - upstream_timeout detail: type: string suggestion: type: string retryable: type: boolean request_id: type: string upgrade_url: type: string format: uri description: 'credits_exhausted and plan_required: where to upgrade the plan.' credits_needed: type: integer description: 'API credit refusals: what the call needed.' credits_remaining: type: integer description: >- API credit refusals: what is left (of the month, or of the day for daily_credit_cap_exceeded). resets_at: type: string format: date-time description: >- credits_exhausted and daily_credit_cap_exceeded: when the limit resets. required: - type - title - status - code - detail - suggestion - retryable - request_id securitySchemes: apiKey: type: http scheme: bearer description: 'An API key: `Authorization: Bearer alura_sk_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.