GET/data/metrics

Query computed financial metrics for many companies in one call — the at-scale primitive for building on the data layer. Supports trend/statistical dimensions and a dry-run credit estimate. Also available as POST for large request bodies.

Example Request

https://api.metricduck.com/api/v1/data/metrics?tickers=AAPL,MSFT&metrics=revenues,roic,gross_margin&period=ttm

Query Parameters

Parameter	Type	Default	Description
`tickers`required	`string`	-	Comma-separated tickers (e.g., AAPL,MSFT,GOOGL). Up to 200 with a free key.
`metrics`required	`string`	-	Comma-separated metric ids (e.g., revenues,roic,gross_margin). 323+ available.
`period`	`string`	`"ttm"`	"ttm", "quarterly", or "annual".
`years`	`integer`	`2`	Years of history (1–10).
`dimensions`	`string`	-	Compound period types for trend/stat analysis (e.g., Q.TREND8,Q.MED8,TTM.YOY).
`price`	`string`	`"historical"`	Price basis for valuation metrics: "historical" (period-end) or "current" (today).
`dry_run`	`boolean`	`false`	Return the credit-cost estimate without querying data.

Response

Nested JSON keyed by ticker, plus metadata including credits used.

Fields

Field	Type	Description
`data`	`object`	Company data keyed by ticker; each holds the requested metrics and values.
`metadata`	`object`	Request echo, period info, and credit usage.

Example Response

{
  "data": {
    "AAPL": {
      "metrics": {
        "revenues": { "ttm": 399000000000 },
        "roic": { "ttm": 0.57 },
        "gross_margin": { "ttm": 0.462 }
      }
    },
    "MSFT": { "metrics": { "revenues": { "ttm": 270000000000 } } }
  },
  "metadata": {
    "tickers": ["AAPL", "MSFT"],
    "metrics": ["revenues", "roic", "gross_margin"],
    "period": "ttm",
    "credits_used": 6
  }
}

Code Examples

cURL

curl "https://api.metricduck.com/api/v1/data/metrics?tickers=AAPL,MSFT&metrics=revenues,roic,gross_margin&period=ttm" \
  -H "Authorization: Bearer fda_your_api_key"

Dry run (estimate credits)

# Estimate credit cost before running the real query
curl "https://api.metricduck.com/api/v1/data/metrics?tickers=AAPL,MSFT&metrics=revenues,roic&dry_run=true" \
  -H "Authorization: Bearer fda_your_api_key"

Notes

- Public, but capped for guests — register a free key for up to 200 tickers and all metrics.
- Credit-metered: cost scales with tickers × metrics × periods. Use dry_run=true to estimate first.
- This is the free path to financial metrics (revenue, margins, ROIC…) — the pre-formatted statement endpoints are a separate Pro convenience layer.
- Use POST when the ticker/metric list is large.