MetricDuck Users API
The users API from MetricDuck — 11 operation(s) for users.
The users API from MetricDuck — 11 operation(s) for users.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/metricduck-com:metricduck-com-users-api"
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.
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: 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