Sync API

Stable

Bulk sync company metrics for screener products. Get standardized financial data for your entire universe in a single request.

QuickstartCredit SystemEndpointsErrors

Authentication

Pass your API key in the Authorization header:

Authorization: Bearer fda_your_api_key

Quickstart

import requests

API_KEY = "fda_your_api_key"
BASE_URL = "https://api.metricduck.com"

# Sync top 500 companies with selected metrics
response = requests.post(
    f"{BASE_URL}/screener/sync",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "top_n": 500,
        "metrics": ["pe_ratio", "roic", "gross_margin", "fcf_yield"]
    }
)

data = response.json()
print(f"Synced {data['data_scope']['companies_count']} companies")
print(f"Credits used: {data['credits']['used']}")

Credit System

All tiers have full universe and metrics access. Credits are the only rate limiter:

credits = (companies × metrics × new_quarters × 5) + (companies × metrics × historical_quarters × 1)

Example (100 companies, 50 metrics, latest quarter): 100 × 50 × 1 × 5 = 25,000 credits

Delta sync: Only updated companies are counted, reducing credit usage significantly for incremental updates.

Check remaining: Use GET /screener/sync/status to check credits without consuming any.

Monthly credit limits: Seed: 200K, Launch: 800K, Growth: 3.2M, Scale: 12M. See Pricing for details.

Available metrics: Browse Metrics Catalog to discover valid metric IDs for the metrics parameter.

Endpoints

Bulk sync company metrics for your tier's universe.

Request Body

ParameterTypeDefaultDescription
top_nint-Select top N companies by market cap rank (1-1000). Mutually exclusive with tickers.
tickersstring[]-Explicit list of tickers (max 1000). Mutually exclusive with top_n.
metricsstring[]-Metric IDs to sync (required, max 100). See /metrics for valid IDs.
formatstring"json"Response format: "json" or "csv"
delta_sincedatetimenullISO 8601 timestamp for incremental sync
dry_runboolfalsePreview credit cost without executing sync

Response Structure

{
  "sync_id": "sync_abc123def456",
  "generated_at": "2024-01-15T12:00:00Z",
  "tier": "seed",
  "data_scope": {
    "companies_count": 100,
    "metrics_count": 50,
    "metrics_list": ["market_cap", "pe_ratio", ...],
    "period_types": ["TTM", "Q", "FY"]
  },
  "credits": {
    "used": 25000,
    "total_used_this_month": 50000,
    "monthly_limit": 200000,
    "remaining": 150000
  },
  "data": [
    {
      "ticker": "AAPL",
      "company_name": "Apple Inc.",
      "cik": "0000320193",
      "metrics": {
        "market_cap": { "ttm": 3000000000000, "q_latest": null, "fy_latest": null },
        "pe_ratio": { "ttm": 28.5, "q_latest": 27.2, "fy_latest": 29.1 }
      },
      "updated_at": "2024-01-14T18:30:00Z"
    }
  ],
  "is_delta": false,
  "attribution": { "required": true, "text": "Powered by MetricDuck" }
}

Delta Sync

Use delta_since to get only companies updated since your last sync. This reduces payload size and credit usage.

# Delta sync - only get updates since last sync
response = requests.post(
    f"{BASE_URL}/screener/sync",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "top_n": 500,
        "metrics": ["pe_ratio", "roic", "gross_margin", "fcf_yield"],
        "delta_since": "2024-01-15T00:00:00Z"
    }
)

data = response.json()
print(f"Updated companies: {data['data_scope']['companies_count']}")
print(f"Is delta: {data['is_delta']}")

Error Handling

HTTPError CodeDescription
401authentication_requiredMissing or invalid authentication token
403not_enterprise_tierEnterprise tier required (seed/launch/growth/scale)
400invalid_filterRequested metrics/tickers not allowed for tier
429quota_exceededMonthly credit limit exceeded
500billing_errorBilling system error - retry the request

Need help? Contact us for dedicated support.