MetricDuck Screener API
The screener API from MetricDuck — 10 operation(s) for screener.
The screener API from MetricDuck — 10 operation(s) for screener.
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-screener-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 Screener API
description: 'SEC filing data API: equity fundamentals updated daily from SEC EDGAR'
version: 2.0.0
tags:
- name: Screener
paths:
/api/v1/screener/metrics:
get:
tags:
- Screener
summary: Get Metrics
description: 'Get all filterable metrics with metadata and hierarchical organization.
Returns:
- Hierarchical structure: Category → Subcategory → Metrics
- Metric metadata: display_name, description, unit, data_type
- 253 metrics across 5 categories (measured 2026-09-16; was documented as 131/4)
Results are cached for 60 minutes (metrics rarely change).'
operationId: get_metrics_api_v1_screener_metrics_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'
/api/v1/screener/curated-metrics:
get:
tags:
- Screener
summary: Get Curated Metrics
description: 'Get curated 24 metrics for simplified screener with presets and metadata.
Returns:
- 24 carefully selected metrics across 5 categories
- 6 growth metrics with explicit period_type (ttm.yoy, ttm.cagr3, ss.yoy)
- 5 curated presets (Growth, Value, Quality, Dividend, Small Cap)
- Filter suggestions and typical ranges per metric
- Formatting rules (decimals, suffix, color coding)
Results cached for 60 minutes (rarely changes).'
operationId: get_curated_metrics_api_v1_screener_curated_metrics_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'
/api/v1/screener/filter-templates:
get:
tags:
- Screener
summary: Get Filter Templates
description: 'Get filter templates for each data type.
Provides suggested filter ranges based on metric data_type.
Returns:
- currency: Market cap ranges (micro, small, mid, large, mega)
- percentage: Common percentage ranges (negative, low, moderate, high)
- ratio: Common ratio ranges (valuation multiples, etc.)
- days: Day ranges (DSO, DIO, etc.)
- shares: Share count ranges'
operationId: get_filter_templates_api_v1_screener_filter_templates_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/api/v1/screener/screen:
post:
tags:
- Screener
summary: Screen Companies
description: 'Screen companies using dynamic metric filters.
Serves the latest-snapshot values (rebuilt every ~12h — the same freshness
contract as the overview/factsheet surfaces). Supports dynamic filter
arrays, custom operators (lt, lte, gt, gte, eq, between), dynamic column
selection, and flexible sorting.'
operationId: screen_companies_api_v1_screener_screen_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/ScreenRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/screener/health:
get:
tags:
- Screener
summary: Screener Health
description: Health check endpoint for screener
operationId: screener_health_api_v1_screener_health_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/api/v1/screener/benchmarks/software:
get:
tags:
- Screener
summary: Get Software Benchmarks
description: 'Get financial benchmarks for software companies (SIC 7370-7379).
**Metrics Included:**
- **Rule of 40**: Revenue Growth + EBITDA Margin (industry standard)
- **Gross Margin**: Software scalability indicator (70%+ expected)
- **FCF Margin**: Cash generation efficiency
- **EBITDA Margin**: Operating profitability
- **Net Margin**: Bottom-line profitability
- **ROIC**: Included with caveat (misleading for asset-light businesses)
**Why Rule of 40 over ROIC:**
Practitioners (VCs, PE, public equity analysts) primarily use Rule of 40
for software companies because:
1. Software has near-zero invested capital → ROIC denominator problems
2. Rule of 40 balances growth vs profitability trade-off
3. Correlates strongly with valuations (McKinsey, BCG research)
**Benchmark Statistics:**
- P25 (25th percentile): Bottom quartile
- Median (50th percentile): Typical for software
- P75 (75th percentile): Top quartile
**Cache:** Results cached for 6 hours.'
operationId: get_software_benchmarks_api_v1_screener_benchmarks_software_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/SoftwareBenchmarks'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/screener/benchmarks/{metric_id}/sectors:
get:
tags:
- Screener
summary: Get Metric Sector Benchmarks
description: 'Get sector benchmarks for any metric.
Returns percentile-based benchmarks (P25, Median, P75) by sector,
computed from the latest filing data for each company.
**Supported Metrics:**
Any metric_id from filing_metrics table (250+ metrics available).
Common examples: gross_margin, oper_margin, net_margin, roe, roa,
debt_to_equity, current_ratio, asset_turnover, etc.
**Sectors Included:**
- Retail & Consumer Goods (SIC 5200-5999)
- Manufacturing & Industrials (SIC 2000-3999)
- Healthcare & Pharmaceuticals (SIC 8000-8099)
- Utilities & Infrastructure (SIC 4900-4999)
- Transportation & Logistics (SIC 4000-4799)
- Energy & Resources (SIC 1000-1499)
- Technology (SIC 7000-7999)
- Financial Services (SIC 6000-6499)
- Real Estate (SIC 6500-6799)
**Cache:** Results cached for 6 hours.'
operationId: get_metric_sector_benchmarks_api_v1_screener_benchmarks__metric_id__sectors_get
security:
- HTTPBearer: []
- APIKeyHeader: []
parameters:
- name: metric_id
in: path
required: true
schema:
type: string
pattern: ^[a-z][a-z0-9_]*$
description: Metric ID (e.g., 'gross_margin', 'roe', 'debt_to_equity')
title: Metric Id
description: Metric ID (e.g., 'gross_margin', 'roe', 'debt_to_equity')
- name: period
in: query
required: false
schema:
type: string
pattern: ^(ttm|annual|quarterly)$
description: 'Period type: ''ttm'', ''annual'', or ''quarterly'''
default: ttm
title: Period
description: 'Period type: ''ttm'', ''annual'', or ''quarterly'''
- 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/MetricBenchmarkList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/screener/benchmarks/{metric_id}/sectors/{sector}:
get:
tags:
- Screener
summary: Get Metric Sector Benchmark
description: 'Get benchmark for a specific metric and sector.
Returns percentile statistics for a single sector.'
operationId: get_metric_sector_benchmark_api_v1_screener_benchmarks__metric_id__sectors__sector__get
security:
- HTTPBearer: []
- APIKeyHeader: []
parameters:
- name: metric_id
in: path
required: true
schema:
type: string
pattern: ^[a-z][a-z0-9_]*$
description: Metric ID
title: Metric Id
description: Metric ID
- name: sector
in: path
required: true
schema:
type: string
pattern: ^[A-Z_]+$
description: Sector code (e.g., 'TECHNOLOGY', 'HEALTHCARE')
title: Sector
description: Sector code (e.g., 'TECHNOLOGY', 'HEALTHCARE')
- name: period
in: query
required: false
schema:
type: string
pattern: ^(ttm|annual|quarterly)$
description: 'Period type: ''ttm'', ''annual'', or ''quarterly'''
default: ttm
title: Period
description: 'Period type: ''ttm'', ''annual'', or ''quarterly'''
- 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/src__models__benchmarks__MetricBenchmark'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/screener/benchmarks/available:
get:
tags:
- Screener
summary: List Available Benchmark Metrics
description: 'List metrics available for benchmarking.
Returns metrics that have sufficient data coverage across sectors.
Useful for discovering which metrics can be used for research pages.'
operationId: list_available_benchmark_metrics_api_v1_screener_benchmarks_available_get
parameters:
- name: period
in: query
required: false
schema:
type: string
pattern: ^(ttm|annual|quarterly)$
description: Period type to check availability
default: ttm
title: Period
description: Period type to check availability
- name: min_companies
in: query
required: false
schema:
type: integer
minimum: 10
description: Minimum companies required across all sectors
default: 100
title: Min Companies
description: Minimum companies required across all sectors
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/screener/taxonomy:
get:
tags:
- Screener
summary: Get Sector Taxonomy
description: 'Get sector taxonomy for ROIC screener.
Returns:
- **sectors**: List of benchmark sectors with their unified code mappings
- **default_sectors**: Sector codes selected by default (excludes warning sectors)
- **warning_sectors**: Sectors with unreliable benchmarks (TECHNOLOGY, FINANCIAL, REAL_ESTATE)
- **unified_to_benchmark**: Map from unified sector code to benchmark sector code
- **benchmark_to_unified**: Map from benchmark sector code to list of unified codes
**Use Case:**
Frontend fetches this once on page load to build sector filter UI
without hardcoding sector mappings.
**Cache:** Response is immutable configuration - cache aggressively (24h+).'
operationId: get_sector_taxonomy_api_v1_screener_taxonomy_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SectorTaxonomyResponse'
components:
schemas:
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
BenchmarkSector:
properties:
code:
type: string
title: Code
name:
type: string
title: Name
unified_codes:
items:
type: string
type: array
title: Unified Codes
default_selected:
type: boolean
title: Default Selected
description:
anyOf:
- type: string
- type: 'null'
title: Description
warning:
anyOf:
- type: string
- type: 'null'
title: Warning
type: object
required:
- code
- name
- unified_codes
- default_selected
title: BenchmarkSector
description: A benchmark sector with its unified code mappings.
src__models__benchmarks__MetricBenchmark:
properties:
sector_code:
type: string
title: Sector Code
description: Sector code (e.g., 'TECHNOLOGY', 'HEALTHCARE')
sector_name:
type: string
title: Sector Name
description: Human-readable sector name
period:
type: string
title: Period
description: 'Period type: ''ttm'', ''annual'', or ''quarterly'''
median:
type: number
title: Median
description: Median value across companies in sector
p25:
type: number
title: P25
description: 25th percentile (bottom quartile threshold)
p75:
type: number
title: P75
description: 75th percentile (top quartile threshold)
min_value:
type: number
title: Min Value
description: Minimum value in sector
max_value:
type: number
title: Max Value
description: Maximum value in sector
company_count:
type: integer
title: Company Count
description: Number of companies included in benchmark
as_of_date:
type: string
title: As Of Date
description: Benchmark calculation date (YYYY-MM-DD)
has_warning:
type: boolean
title: Has Warning
description: True if sector benchmarks may be unreliable for this metric
default: false
type: object
required:
- sector_code
- sector_name
- period
- median
- p25
- p75
- min_value
- max_value
- company_count
- as_of_date
title: MetricBenchmark
description: "Sector benchmark statistics for any metric.\n\nProvides percentile-based benchmarks (P25, Median, P75) to enable\nsector-aware analysis and research page generation.\n\nExample:\n {\n \"sector_code\": \"TECHNOLOGY\",\n \"sector_name\": \"Technology\",\n \"period\": \"ttm\",\n \"median\": 0.652,\n \"p25\": 0.485,\n \"p75\": 0.782,\n \"min_value\": 0.125,\n \"max_value\": 0.924,\n \"company_count\": 847\n }"
src__routes__screener__software_benchmarks__MetricBenchmark:
properties:
metric_id:
type: string
title: Metric Id
description: Metric identifier
metric_name:
type: string
title: Metric Name
description: Human-readable metric name
p25:
anyOf:
- type: number
- type: 'null'
title: P25
description: 25th percentile
median:
anyOf:
- type: number
- type: 'null'
title: Median
description: 50th percentile (median)
p75:
anyOf:
- type: number
- type: 'null'
title: P75
description: 75th percentile
min_value:
anyOf:
- type: number
- type: 'null'
title: Min Value
description: Minimum value
max_value:
anyOf:
- type: number
- type: 'null'
title: Max Value
description: Maximum value
company_count:
type: integer
title: Company Count
description: Number of companies in sample
unit:
type: string
title: Unit
description: Unit of measurement
default: '%'
interpretation:
anyOf:
- type: string
- type: 'null'
title: Interpretation
description: How to interpret this metric
type: object
required:
- metric_id
- metric_name
- company_count
title: MetricBenchmark
description: Benchmark statistics for a single metric.
SoftwareBenchmarks:
properties:
metrics:
items:
$ref: '#/components/schemas/src__routes__screener__software_benchmarks__MetricBenchmark'
type: array
title: Metrics
description: Benchmark statistics for each metric
total_companies:
type: integer
title: Total Companies
description: Total software companies in dataset
industry_description:
type: string
title: Industry Description
description: Industry classification
default: Software (SIC 7370-7379)
methodology_notes:
type: string
title: Methodology Notes
description: Notes on methodology and limitations
default: 'Benchmarks based on TTM metrics. Rule of 40 = Revenue Growth (YoY) + EBITDA Margin. ROIC included with caveat: software''s near-zero invested capital makes traditional ROIC misleading. Source methodology: McKinsey ''SaaS and the Rule of 40'', BCG ''Rule of 40 Lessons''.'
as_of_date:
type: string
title: As Of Date
description: Date benchmarks were calculated
generated_at:
type: string
title: Generated At
description: Timestamp of generation
type: object
required:
- metrics
- total_companies
- as_of_date
- generated_at
title: SoftwareBenchmarks
description: Complete software sector financial benchmarks.
MetricBenchmarkList:
properties:
metric_id:
type: string
title: Metric Id
description: Metric identifier (e.g., 'gross_margin')
metric_name:
type: string
title: Metric Name
description: Human-readable metric name
metric_unit:
type: string
title: Metric Unit
description: Unit of measurement (e.g., 'percent', 'ratio', 'usd')
metric_description:
anyOf:
- type: string
- type: 'null'
title: Metric Description
description: Description of what this metric measures
benchmarks:
items:
$ref: '#/components/schemas/src__models__benchmarks__MetricBenchmark'
type: array
title: Benchmarks
description: List of sector benchmarks
total_sectors:
type: integer
title: Total Sectors
description: Total number of sectors included
total_companies:
type: integer
title: Total Companies
description: Total companies across all sectors
period:
type: string
title: Period
description: Period type for all benchmarks
generated_at:
type: string
title: Generated At
description: Timestamp when benchmarks were generated
type: object
required:
- metric_id
- metric_name
- metric_unit
- benchmarks
- total_sectors
- total_companies
- period
- generated_at
title: MetricBenchmarkList
description: 'Response model for sector benchmark list endpoint.
Returns all sector benchmarks with metric metadata.'
SectorTaxonomyResponse:
properties:
sectors:
items:
$ref: '#/components/schemas/BenchmarkSector'
type: array
title: Sectors
default_sectors:
items:
type: string
type: array
title: Default Sectors
warning_sectors:
items:
type: string
type: array
title: Warning Sectors
unified_to_benchmark:
additionalProperties:
type: string
type: object
title: Unified To Benchmark
benchmark_to_unified:
additionalProperties:
items:
type: string
type: array
type: object
title: Benchmark To Unified
version:
type: string
title: Version
type: object
required:
- sectors
- default_sectors
- warning_sectors
- unified_to_benchmark
- benchmark_to_unified
- version
title: SectorTaxonomyResponse
description: Response model for sector taxonomy endpoint.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
MetricFilter:
properties:
metric_id:
type: string
title: Metric Id
description: Metric identifier (e.g., 'pe_ratio')
period_type:
anyOf:
- type: string
- type: 'null'
title: Period Type
description: 'Period type: ''ttm'', ''ss'', or growth metrics like ''ttm.yoy'''
default: ttm
operator:
type: string
title: Operator
description: 'Comparison operator: lt, lte, gt, gte, eq, between'
value:
anyOf:
- type: number
- type: 'null'
title: Value
description: Single value for lt/lte/gt/gte/eq operators
min_value:
anyOf:
- type: number
- type: 'null'
title: Min Value
description: Minimum value for 'between' operator
max_value:
anyOf:
- type: number
- type: 'null'
title: Max Value
description: Maximum value for 'between' operator
type: object
required:
- metric_id
- operator
title: MetricFilter
description: A single metric filter condition
ScreenRequest:
properties:
filters:
items:
$ref: '#/components/schemas/MetricFilter'
type: array
title: Filters
description: List of metric filters to apply
default: []
include_metrics:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Include Metrics
description: List of metric IDs to include in results. If null, returns common metrics.
sectors:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Sectors
description: List of sector codes to filter by (e.g., ['TECH', 'HEALTH'])
industries:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Industries
description: List of industry codes to filter by (e.g., ['TECH_SOFTWARE'])
tickers:
anyOf:
- items:
type: string
type: array
maxItems: 50
- type: 'null'
title: Tickers
description: Filter to specific ticker symbols (max 50). Returns only these companies.
required_tags:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Required Tags
description: Filter to companies whose classification includes ALL of these tags (e.g., ['saas_enterprise']).
excluded_tags:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Excluded Tags
description: Filter to companies whose classification includes NONE of these tags (e.g., ['china_revenue_heavy']).
signals:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Signals
description: DEPRECATED (#1535) — no longer accepted; a non-empty value returns 400. Signal screening moved to screen_filing_signals (a universe-correct cross-company screen); intersect its results with your metric screen. Kept only to fail loudly instead of silently ignoring the field.
deprecated: true
limit:
type: integer
maximum: 100.0
minimum: 1.0
title: Limit
description: Maximum number of results per page
default: 20
page:
type: integer
minimum: 1.0
title: Page
description: Page number (1-indexed) for pagination
default: 1
sort_by:
type: string
title: Sort By
description: Metric ID to sort by
default: market_cap
sort_order:
type: string
title: Sort Order
description: 'Sort order: asc or desc'
default: desc
type: object
title: ScreenRequest
description: Request body for POST /screener/screen
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key