> ## Documentation Index > Fetch the complete documentation index at: https://docs.findly.icu/llms.txt > Use this file to discover all available pages before exploring further. # Get usage > Returns the plan, today's quota and the modules open to the account that owns the key. Never billed and never runs a search: use it to check that a key works. ## OpenAPI ````yaml /openapi.json get /api/v1/usage openapi: 3.1.0 info: title: Find.ly API version: 1.0.0 description: >- Search leak and OSINT data from your own code with the same five modules, quota and limits as the Find.ly dashboard. API access comes with the Professional and Enterprise plans. Every search is `POST /api/v1/search/{module}`, where `{module}` is one of `intelligence-search`, `phonebook`, `identity-portal`, `system-id`, `storage-id`. Each module has its own reference page below because each takes a different body. servers: - url: https://findly.icu description: Production security: - bearerAuth: [] - apiKeyHeader: [] tags: - name: Account description: 'Plan and quota. Free: never billed.' - name: Search description: One request per served search. paths: /api/v1/usage: get: tags: - Account summary: Get usage description: >- Returns the plan, today's quota and the modules open to the account that owns the key. Never billed and never runs a search: use it to check that a key works. operationId: get_usage responses: '200': description: Plan, quota and modules. `billed` is always `false`. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' X-Quota-Limit: $ref: '#/components/headers/XQuotaLimit' X-Quota-Remaining: $ref: '#/components/headers/XQuotaRemaining' X-Quota-Reset: $ref: '#/components/headers/XQuotaReset' content: application/json: schema: $ref: '#/components/schemas/UsageResponse' examples: usage: value: username: acme-security modules: - intelligence-search - phonebook - identity-portal - system-id - storage-id billed: false usage: plan: Professional plan_expires_at: '2026-10-16T12:00:00.000Z' daily_quota: 500 used: 13 remaining: 487 resets_at: '2026-09-17T00:00:00.000Z' '400': description: Bad request. `api_key_in_url`. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: api_key_in_url: value: error: code: api_key_in_url message: >- Send your API key in the Authorization header, never in the URL. If it was logged somewhere, regenerate it from your dashboard. billed: false '401': description: Missing or invalid API key. `missing_api_key`, `invalid_api_key`. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' WWW-Authenticate: $ref: '#/components/headers/WWWAuthenticate' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_api_key: value: error: code: missing_api_key message: >- Send your API key in the Authorization header: "Authorization: Bearer fly_live_…". billed: false invalid_api_key: value: error: code: invalid_api_key message: >- This API key is not valid. Copy it again from the API page of your dashboard. billed: false '403': description: >- Access refused. `account_suspended`, or `plan_required` (the plan has no API access; carries `usage` and `X-Quota-*`). headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' X-Quota-Limit: $ref: '#/components/headers/XQuotaLimit' X-Quota-Remaining: $ref: '#/components/headers/XQuotaRemaining' X-Quota-Reset: $ref: '#/components/headers/XQuotaReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: account_suspended: value: error: code: account_suspended message: >- This account is suspended. If you think this is a mistake, contact us. billed: false plan_required: value: error: code: plan_required message: >- Your Starter plan doesn’t include API access. It comes with the Professional and Enterprise plans. plan: Starter billed: false usage: plan: Starter plan_expires_at: '2026-10-16T12:00:00.000Z' daily_quota: 100 used: 0 remaining: 100 resets_at: '2026-09-17T00:00:00.000Z' '429': description: Too many calls from this IP address. `too_many_requests`. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: too_many_requests: value: error: code: too_many_requests message: >- Too many API calls from this address. Slow down and try again. billed: false '500': description: Unexpected server error. `internal_error`. No request was used. headers: Cache-Control: $ref: '#/components/headers/CacheControl' X-Request-Billed: $ref: '#/components/headers/XRequestBilled' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: value: error: code: internal_error message: Something went wrong on our side. No request was used. billed: false components: headers: CacheControl: description: Always `no-store`. schema: type: string const: no-store XRequestBilled: description: >- `true` if this call used one request from the daily quota, otherwise `false`. schema: type: string enum: - 'true' - 'false' XQuotaLimit: description: >- Daily quota of the plan. Sent whenever the account quota is known (not on authentication or IP-limit errors). schema: type: string examples: - '500' XQuotaRemaining: description: Requests left today, after this call. schema: type: string examples: - '487' XQuotaReset: description: ISO 8601 time of the next reset (02:00 Europe/Paris). schema: type: string format: date-time WWWAuthenticate: description: >- `Bearer realm="Find.ly API"`, with `error="invalid_token"` for `invalid_api_key`. schema: type: string RetryAfter: description: Seconds to wait before retrying (at least 1). schema: type: string examples: - '3' schemas: UsageResponse: type: object required: - username - modules - billed - usage properties: username: type: string description: Username of the account that owns the key. modules: type: array description: Module slugs open to this plan. items: type: string enum: - intelligence-search - phonebook - identity-portal - system-id - storage-id billed: type: boolean const: false usage: $ref: '#/components/schemas/Usage' ErrorResponse: type: object required: - error - billed properties: error: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- Human-readable. It can change: branch on `code`, not on `message`. fields: type: object additionalProperties: type: string description: '`invalid_input` only. One message per invalid or unknown field.' plan: type: string description: '`plan_required` only. The current plan.' required_plan: type: string description: '`module_locked` only. Cheapest plan that includes the module.' reason: type: string enum: - concurrent - per-minute description: '`rate_limited` only. Which account limit was hit.' upstream_status: type: - integer - 'null' description: >- `upstream_error` only. HTTP status returned by the search service when it sent one (400 or above), otherwise `null`. billed: type: boolean description: Errors are never billed. usage: $ref: '#/components/schemas/Usage' Usage: type: object description: Quota of the account, after the call. required: - plan - plan_expires_at - daily_quota - used - remaining - resets_at properties: plan: type: string enum: - Free - Starter - Professional - Enterprise plan_expires_at: type: - string - 'null' format: date-time description: End of the paid plan. `null` on Free. daily_quota: type: integer description: 'Requests per day: 500 on Professional, 1,500 on Enterprise.' used: type: integer description: Requests used today, dashboard and API combined. remaining: type: integer description: Requests left today. resets_at: type: string format: date-time description: Next reset, 02:00 Europe/Paris. ErrorCode: type: string description: >- Stable, machine-readable error code: - `api_key_in_url`: 400 — an API key was sent in the query string (`key`, `api_key`, `apikey`, `token` or `access_token`). - `invalid_json`: 400 — the body is missing, is not valid UTF-8 JSON, or is not a JSON object. - `unsupported_format`: 400 — `format` is not `json`, or `txt` was asked for a module that has no text output. - `missing_api_key`: 401 — neither `Authorization` nor `X-API-Key` was sent. - `invalid_api_key`: 401 — the key is malformed, unknown, regenerated, or belongs to a deleted account. - `account_suspended`: 403 — the account that owns the key is suspended. - `plan_required`: 403 — the account plan does not include API access (Professional and Enterprise only). - `module_locked`: 403 — the account plan does not include this module. - `unknown_module`: 404 — `{module}` is not one of the five module slugs. - `not_found`: 404 — no API endpoint at this path. - `body_too_large`: 413 — the request body is over 16 KB. - `invalid_input`: 422 — a field is unknown, has the wrong type, or has an invalid value. See `error.fields`. - `too_many_requests`: 429 — more than 60 API calls in one minute from the same IP address. - `quota_exceeded`: 429 — the account has used all of today's requests. - `rate_limited`: 429 — two searches already running, or 20 searches in the last minute, on this account. - `internal_error`: 500 — unexpected server error. No request was used. - `upstream_error`: 502 — the search service failed, timed out, or sent an unreadable or oversized response. The request is refunded. enum: - api_key_in_url - invalid_json - unsupported_format - missing_api_key - invalid_api_key - account_suspended - plan_required - module_locked - unknown_module - not_found - body_too_large - invalid_input - too_many_requests - quota_exceeded - rate_limited - internal_error - upstream_error securitySchemes: bearerAuth: type: http scheme: bearer description: >- `Authorization: Bearer fly_live_…`. Takes precedence when both headers are sent. apiKeyHeader: type: apiKey in: header name: X-API-Key description: >- `X-API-Key: fly_live_…`. Used only when no `Authorization` header is sent. ````