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 per call with a key (10 without), as long as the call's credits fit your budget (see Notes).
`metrics`required	`string`	-	Comma-separated metric ids (e.g., revenues,roic,gross_margin). The allowed ids are listed by GET /api/v1/data/metrics/catalog.
`period`	`string`	`"ttm"`	"ttm", "quarterly", or "annual".
`years`	`integer`	`2`	Years of history (1–10; up to 2 without a key).
`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" (latest end-of-day close).
`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 and counts, plus credits: with a key, the credits this call used and what remains in your budget; null without a key.

Example Response

// GET /api/v1/data/metrics?tickers=AAPL&metrics=revenues&period=quarterly&years=1
{
  "data": {
    "AAPL": {
      "company_name": "Apple Inc.",
      "cik": "0000320193",
      "metrics": {
        "revenues": {
          "display_name": "Revenues",
          "unit": null,
          "values": [
            { "period": "Q4 2026", "period_end": "2026-09-26", "value": 114477000000.0, "dimension": null },
            { "period": "Q3 2026", "period_end": "2026-06-27", "value": 109417000000.0, "dimension": null },
            { "period": "Q2 2026", "period_end": "2026-03-28", "value": 111184000000.0, "dimension": null },
            { "period": "Q1 2026", "period_end": "2025-12-27", "value": 143756000000.0, "dimension": null }
          ]
        }
      }
    }
  },
  "metadata": {
    "request": { "tickers": ["AAPL"], "metrics": ["revenues"], "period": "quarterly", "years": 1, "dimensions": null, "price": "historical" },
    "resolved_tickers": 1,
    "total_values": 4,
    "generated_at": "2026-11-10T02:31:35.466867",
    "warnings": null,
    "credits": null
  }
}

Code Examples

cURL

curl "https://api.metricduck.com/api/v1/data/metrics?tickers=AAPL,MSFT&metrics=revenues,roic,gross_margin&period=ttm" \
  -H "X-API-Key: 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 "X-API-Key: fda_your_api_key"

Notes

- Public, but capped for guests (10 tickers, 15 metrics and 2 years per call, 5 calls a day) — register a free key for up to 200 tickers and all metrics, within your credit budget.
- Credits: each call costs tickers × metrics × periods (periods = years, or years × 4 for quarterly; each dimension adds 1). Free: 500 credits per UTC day. Pro: 50,000 credits a month. Each call also counts as one tool call. Use dry_run=true to estimate first.
- For example, 200 tickers × 1 metric × 2 years of TTM = 400 credits, which fits a free key's daily budget; 200 tickers × 2 metrics × 2 years = 800 does not.
- 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.