financialfilings-com Account API

openapi: 3.2.0
info:
  title: FinancialFilings Account API
  version: 1.4.0
  description: 'Filings and company data for listed companies across the G20 and Europe. Send your API key in the `X-API-Key` header on every request. New here? Start with the quickstart.


    **Credits.** Every call costs credits, and each endpoint below shows its price. `X-Credits-Charged` on the response says what a call cost, and `GET /usage/` shows the month so far. A free account gets a monthly allowance. Webhooks are an Enterprise feature. Pricing: https://financialfilings.com/developers/


    **Rate limits.** Responses carry `X-RateLimit-Burst-Limit` (a rate such as `50/second`), `X-RateLimit-Monthly-Limit`, `X-RateLimit-Monthly-Remaining` and `X-RateLimit-Monthly-Unit` (`requests` or `credits`). All four are strings and can be non-numeric (for example `Unlimited`); the last two are left out when they don''t apply.'
  termsOfService: https://financialfilings.com/api-terms/
  contact:
    name: API Support
    url: https://financialfilings.com/
    email: api@financialfilings.com
servers:
- url: https://api.financialreports.eu
  description: Production API Gateway
tags:
- name: Account
  description: Your own API usage and spend. Free, never billed.
paths:
  /usage/:
    get:
      operationId: usage_retrieve
      description: 'What your API usage has cost this billing cycle: the same numbers as the API dashboard. Pay-as-you-go accounts get cycle spend, credits by category, the daily cap with today''s spend, and the cycle ceiling (`payg`). Free accounts get their monthly credit pool (`free_credits`). Plans metered in requests get their request quota (`requests`). Sections that do not apply to the account are null.


        Free: this endpoint is never billed and does not count toward any quota. Each billed response also carries `X-Credits-Charged` and `X-Credits-Category` headers.'
      summary: Get API Usage and Spend
      tags:
      - Account
      security:
      - ApiKeyAuth: []
      - CognitoJWT: []
      responses:
        '200':
          description: Usage and spend for the authenticated account.
        '403':
          description: Missing or invalid API key, or the plan does not include this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
              examples:
                MissingCredentials:
                  summary: No X-API-Key header
                  value:
                    detail: Authentication credentials were not provided.
                    type: authentication_required
                    resolution: 'Send your API key in the X-API-Key request header, e.g. curl -H "X-API-Key: <your key>" https://api.financialreports.eu/filings/ . A browser address bar never sends this header. No key yet? Get a free one at https://financialfilings.com/accounts/api-dashboard/ .'
                    dashboard_url: https://financialfilings.com/accounts/api-dashboard/
                InvalidKey:
                  summary: Unknown or inactive API key
                  value:
                    detail: Invalid or inactive API key.
                PlanDoesNotPermit:
                  summary: Plan does not include this endpoint
                  value:
                    detail: Your current plan does not permit access. Requires a plan that includes **structured financials**.
        '429':
          description: Rate limit, plan quota or spend cap reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
              examples:
                BurstLimit:
                  summary: Too many requests per minute
                  value:
                    error: Too Many Requests
                    detail: Request was throttled. Expected available in 12 seconds.
                    retry_after_seconds: 12
                    scope: burst
                    type: burst_limit_exceeded
                    message: 'Rate limit reached: 120 requests per minute.'
                    resolution: 'Retry after 12 seconds (Retry-After header). Pay-as-you-go raises this to 50/sec: https://financialfilings.com/accounts/payg/'
                    rate_limit: 120/minute
                    payg_url: https://financialfilings.com/accounts/payg/
components:
  schemas:
    RateLimitError:
      type: object
      description: Body of a 429 response. The `Retry-After` header carries the same wait as `retry_after_seconds`. Only `detail` is always present.
      properties:
        detail:
          type: string
          description: A human-readable message describing the error.
        error:
          type: string
          description: Always `Too Many Requests`.
        retry_after_seconds:
          type:
          - integer
          - 'null'
          description: Seconds until the request may be retried, when known.
        scope:
          type:
          - string
          - 'null'
          description: Which limit was hit, e.g. `burst`, `quota` or `payg_velocity`.
        type:
          type: string
          description: Machine-readable error code, e.g. `burst_limit_exceeded`, `quota_limit_exceeded`, `daily_spend_cap_reached` or `monthly_spend_ceiling_reached`.
        message:
          type: string
          description: A human-readable explanation of the limit.
        resolution:
          type: string
          description: A human-readable hint on what to do next.
        upgrade_url:
          type: string
          description: 'Where to upgrade: the pay-as-you-go card page for free accounts, else the plans page (quota errors).'
        limit:
          type: integer
          description: The plan allowance that was used up (quota errors).
        interval:
          type: string
          description: '`monthly` or `annual` (quota errors).'
        resets_on:
          type: string
          format: date
          description: UTC date the allowance resets (quota errors).
        rate_limit:
          type: string
          description: The per-minute limit that refused the request, e.g. `120/minute` (burst errors).
        payg_url:
          type: string
          description: Where to enable pay-as-you-go (quota and burst errors, when it applies).
        dashboard_url:
          type: string
          description: Where to see current spend (spend-cap and spend-ceiling errors).
        contact_url:
          type: string
          description: Where to ask for a higher limit (spend-cap and spend-ceiling errors).
      required:
      - detail
    ErrorDetail:
      type: object
      properties:
        detail:
          type: string
          description: A human-readable message describing the error.
        type:
          type: string
          description: Machine-readable error code, e.g. `authentication_required`. Present on some errors only.
        resolution:
          type: string
          description: A human-readable hint on how to fix the request. Present on some errors only.
        error_type:
          type: string
          description: Machine-readable error code on validation errors. Present on some errors only.
      required:
      - detail
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Server-to-server API key authentication. Provide your key in the `X-API-Key` request header. Keys can be generated and rotated from your account dashboard: https://financialfilings.com/profile/'
    CognitoJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'AWS Cognito-issued JWT access token. Provide the token in the `Authorization` header as: `Authorization: Bearer <access_token>`. Tokens are issued via the Cognito hosted UI or the OAuth2 authorization code flow at `https://auth.financialreports.eu`.'