MetricDuck Users API

The users API from MetricDuck — 11 operation(s) for users.

GitHub OpenAPI

Operations 13

GET /users/profile Get User Profile #
PUT /users/profile Update User Profile #
GET /users/usage Get Usage Statistics #
GET /users/usage/daily Get Daily Usage #
GET /users/usage/logs Get Usage Logs #
GET /users/subscription Get Subscription Info #
DELETE /users/account Delete Account #
POST /users/reset-usage Reset Monthly Usage #
POST /users/internal/reset-monthly-api-usage Reset Monthly Api Usage Internal #
POST /users/api-keys Create Api Key #
GET /users/api-keys List Api Keys #
DELETE /users/api-keys/{key_id} Revoke Api Key #
PATCH /users/api-keys/{key_id}/toggle Toggle Api Key #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/metricduck-com:metricduck-com-users-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

metricduck-com-users-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Metric Duck Users API
  description: 'SEC filing data API: equity fundamentals updated daily from SEC EDGAR'
  version: 2.0.0
tags:
- name: Users
paths:
  /users/profile:
    get:
      tags:
      - Users
      summary: Get User Profile
      description: 'Get current user profile.


        Returns an explicit whitelist (UserProfileResponse), NOT the raw `users` row —

        stripe_*/utm_*/internal counters must never reach the client (#1556). Building

        the model field-by-field (never passing profile_data through) plus the

        response_model make the whitelist structural, not a comment.'
      operationId: get_user_profile_users_profile_get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: api_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Users
      summary: Update User Profile
      description: Update user profile information
      operationId: update_user_profile_users_profile_put
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: api_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserProfileUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /users/usage:
    get:
      tags:
      - Users
      summary: Get Usage Statistics
      description: Get current user's API usage statistics
      operationId: get_usage_statistics_users_usage_get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: api_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageStatsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /users/usage/daily:
    get:
      tags:
      - Users
      summary: Get Daily Usage
      description: 'Free-tier daily DATA-API CREDIT usage (credit_ledger); the web meter reads /users/usage.


        Free tier has a per-day cap that resets midnight UTC; paid tiers don''t

        (has_daily_cap=False).


        ⚠ #2357 — a zero from this ledger is UNFALSIFIABLE. `credit_ledger` is written by

        exactly one route (`GET /api/v1/data/metrics`), so `used_today == 0` cannot

        distinguish "consumed nothing" from "consumed a plane this ledger cannot see". It

        held 3 rows all-time against 157,273 lifetime MCP calls, and this endpoint served

        "0 / 500 · 500 left" 653 times to 29 users — one of them on a 3,577-call day. We

        therefore WITHHOLD rather than assert: no metered consumption ⇒ has_daily_cap=False,

        instead of reporting a fabricated zero as fact.


        This deliberately does NOT change enforcement, and does NOT repoint the counter at

        `api_usage_logs` — that would swap a fabricated zero for a fan-out over-count AND

        make the 429 at data_api.py:263 newly reachable, i.e. switch on enforcement inside

        a decision that was explicitly "no enforcement".'
      operationId: get_daily_usage_users_usage_daily_get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: api_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyUsageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /users/usage/logs:
    get:
      tags:
      - Users
      summary: Get Usage Logs
      description: The current user's real product calls (MCP / API key on /api/v1/), newest first.
      operationId: get_usage_logs_users_usage_logs_get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 100
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: api_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiUsageLogResponse'
                title: Response Get Usage Logs Users Usage Logs Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /users/subscription:
    get:
      tags:
      - Users
      summary: Get Subscription Info
      description: Get current user's subscription information
      operationId: get_subscription_info_users_subscription_get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: api_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /users/account:
    delete:
      tags:
      - Users
      summary: Delete Account
      description: 'Delete user account and all associated data.


        Refused (409) while a Stripe subscription can still charge the user; see

        _refuse_delete_while_subscription_can_charge. Refused (503) unless the user''s MCP OAuth

        grants are revoked first; see _revoke_mcp_oauth_grants.'
      operationId: delete_account_users_account_delete
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: api_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /users/reset-usage:
    post:
      tags:
      - Users
      summary: Reset Monthly Usage
      description: Reset monthly usage counter (admin or development only)
      operationId: reset_monthly_usage_users_reset_usage_post
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: api_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /users/internal/reset-monthly-api-usage:
    post:
      tags:
      - Users
      summary: Reset Monthly Api Usage Internal
      description: 'Internal endpoint for Cloud Scheduler to reset monthly API request counters.


        Called automatically on the 1st of each month.

        This endpoint calls the PostgreSQL function reset_monthly_api_requests().


        Security: Requires valid OIDC token from Cloud Scheduler service account.'
      operationId: reset_monthly_api_usage_internal_users_internal_reset_monthly_api_usage_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /users/api-keys:
    post:
      tags:
      - Users
      summary: Create Api Key
      description: 'Create a new API key for the authenticated user.

        The actual key is only shown once during creation.

        Rate limit: Maximum 10 active keys per account.'
      operationId: create_api_key_users_api_keys_post
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: api_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Users
      summary: List Api Keys
      description: List all API keys for the authenticated user
      operationId: list_api_keys_users_api_keys_get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: api_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKeyListItem'
                title: Response List Api Keys Users Api Keys Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /users/api-keys/{key_id}:
    delete:
      tags:
      - Users
      summary: Revoke Api Key
      description: Revoke (delete) an API key
      operationId: revoke_api_key_users_api_keys__key_id__delete
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          title: Key Id
      - name: api_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /users/api-keys/{key_id}/toggle:
    patch:
      tags:
      - Users
      summary: Toggle Api Key
      description: Toggle API key status between active and inactive
      operationId: toggle_api_key_users_api_keys__key_id__toggle_patch
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          title: Key Id
      - name: api_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ApiUsageLogResponse:
      properties:
        id:
          type: string
          title: Id
        endpoint:
          type: string
          title: Endpoint
        method:
          type: string
          title: Method
        status_code:
          type: integer
          title: Status Code
        response_time_ms:
          type: integer
          title: Response Time Ms
        ip_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Ip Address
        created_at:
          type: string
          title: Created At
      type: object
      required:
      - id
      - endpoint
      - method
      - status_code
      - response_time_ms
      - ip_address
      - created_at
      title: ApiUsageLogResponse
      description: API usage log entry
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ApiKeyResponse:
      properties:
        id:
          type: string
          title: Id
        key:
          type: string
          title: Key
        name:
          type: string
          title: Name
        key_prefix:
          type: string
          title: Key Prefix
        created_at:
          type: string
          title: Created At
      type: object
      required:
      - id
      - key
      - name
      - key_prefix
      - created_at
      title: ApiKeyResponse
      description: API key response - only shown once during creation
    ApiKeyCreate:
      properties:
        name:
          type: string
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z0-9\s\-_]+$
          title: Name
          description: API key name (alphanumeric, spaces, hyphens, underscores only)
      type: object
      required:
      - name
      title: ApiKeyCreate
      description: API key creation request
    DailyUsageResponse:
      properties:
        subscription_tier:
          type: string
          title: Subscription Tier
        has_daily_cap:
          type: boolean
          title: Has Daily Cap
        used_today:
          type: integer
          title: Used Today
        daily_limit:
          type: integer
          title: Daily Limit
        remaining:
          type: integer
          title: Remaining
        usage_percentage:
          type: number
          title: Usage Percentage
        resets_at:
          type: string
          title: Resets At
        counts_scope:
          type: string
          title: Counts Scope
          default: data_api_credits
      type: object
      required:
      - subscription_tier
      - has_daily_cap
      - used_today
      - daily_limit
      - remaining
      - usage_percentage
      - resets_at
      title: DailyUsageResponse
      description: 'Free-tier daily DATA-API CREDIT usage (credit_ledger). The web no longer reads it: the

        quota-wall meter shows /users/usage `tool_calls_today`, the free daily cap''s own counter.


        ⚠ #2357 — this is NOT "tool-call usage", which is what it used to claim. The only

        thing it can count is `credit_ledger`, and the only writer of that ledger is

        `GET /api/v1/data/metrics` (credit_service.py:185 ← data_api.py:373). MCP connector

        traffic never touches that route, so for an MCP user this ledger reads 0 no matter

        how much they use the product.


        has_daily_cap=False means "no daily figure can be asserted" — either a paid tier

        (no daily cap) or a free user with no metered consumption to report: see

        `counts_scope`.'
    UsageStatsResponse:
      properties:
        current_month_requests:
          type: integer
          title: Current Month Requests
        monthly_request_limit:
          type: integer
          title: Monthly Request Limit
        usage_percentage:
          type: number
          title: Usage Percentage
        subscription_tier:
          type: string
          title: Subscription Tier
        request_reset_date:
          type: string
          title: Request Reset Date
        credits_used:
          anyOf:
          - type: integer
          - type: 'null'
          title: Credits Used
        credits_remaining:
          anyOf:
          - type: integer
          - type: 'null'
          title: Credits Remaining
        monthly_credit_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Monthly Credit Limit
        last_call_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Call At
        tool_calls_today:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tool Calls Today
        tool_calls_this_month:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tool Calls This Month
        daily_tool_call_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Daily Tool Call Limit
        monthly_tool_call_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Monthly Tool Call Limit
        allowance_label:
          type: string
          title: Allowance Label
          default: ''
        counted_since:
          anyOf:
          - type: string
          - type: 'null'
          title: Counted Since
        count_started_this_month:
          type: boolean
          title: Count Started This Month
          default: false
        daily_cap_enforced:
          type: boolean
          title: Daily Cap Enforced
          default: false
        upgrade_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Upgrade Url
      type: object
      required:
      - current_month_requests
      - monthly_request_limit
      - usage_percentage
      - subscription_tier
      - request_reset_date
      title: UsageStatsResponse
      description: 'User usage statistics.


        The ``tool_calls_*`` fields are the count the tool-call allowance is measured in: the same

        shared counter and unit the free daily cap uses (middleware/free_daily_cap.py), one per MCP

        tool call (its signed sid) or per REST ``fda_`` request, never per internal api request.

        None means "not known" (internal account, counter unreachable), never zero.'
    UserProfileUpdate:
      properties:
        full_name:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Full Name
        company_name:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Company Name
        website_url:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Website Url
      type: object
      title: UserProfileUpdate
      description: User profile update model
    UserProfileResponse:
      properties:
        user_id:
          type: string
          title: User Id
        email:
          type: string
          title: Email
        subscription_tier:
          type: string
          title: Subscription Tier
        full_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Full Name
        company_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Name
        website_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Website Url
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
        subscription_start_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Subscription Start Date
        subscription_end_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Subscription End Date
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        updated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Updated At
      type: object
      required:
      - user_id
      - email
      - subscription_tier
      title: UserProfileResponse
      description: 'Owner-facing profile response — an explicit field WHITELIST (#1556).


        NEVER the raw `users` row: that carries billing (`stripe_*`), marketing

        attribution (`utm_*`), and internal quota counters, which a `SELECT *`-minus-id

        handler leaked to the client. Only the account owner''s own display/identity

        fields belong here; quota counters are served (credit-augmented) by

        `/users/usage` + `/users/subscription`.


        Display fields are Optional: `ensure_user_profile`''s create-on-missing path

        populates only id/email/subscription_tier/counters, so a brand-new user''s row

        has no full_name/company_name/etc. — required fields there would 500.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ApiKeyListItem:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        key_prefix:
          type: string
          title: Key Prefix
        status:
          type: string
          title: Status
        last_used_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Used At
        usage_count:
          type: integer
          title: Usage Count
        created_at:
          type: string
          title: Created At
      type: object
      required:
      - id
      - name
      - key_prefix
      - status
      - last_used_at
      - usage_count
      - created_at
      title: ApiKeyListItem
      description: API key list item - without the actual key
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key