API Overview

Authentication, rate limits, and error handling for the Metric Duck API.

Base URL

https://api.metricduck.com/api/v1

All endpoints are relative to this base URL. The API uses HTTPS only.

Authentication

Authenticate API requests by including your API key in the Authorization header as a Bearer token.

curl -X GET "https://api.metricduck.com/api/v1/companies/universe?limit=10" \
  -H "Authorization: Bearer fda_your_api_key_here"

Security Best Practices

- Never expose API keys in client-side code
- Store keys in environment variables
- Use different keys for development and production
- Rotate keys periodically

API Key Prefixes:

fda_ - Production keys
md_test_ - Test/development keys

Generate API keys from your Dashboard → Developer

Rate Limits

Rate limits vary by subscription tier. Free resets daily (midnight UTC); Pro resets monthly.

Tier	Monthly Requests	Price
Free	500 credits/day	$0
Pro	50,000 credits/month	$20/month

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit - Monthly request limit
X-RateLimit-Remaining - Requests remaining this month
X-RateLimit-Reset - UTC timestamp when limit resets

Need higher limits? View pricing plans

Error Handling

The API uses standard HTTP status codes. Error responses include a JSON body with details.

Error Response Format

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "status": 401
  }
}

Status	Name	Description
`400`	Bad Request	Invalid request parameters or malformed request body
`401`	Unauthorized	Missing or invalid API key in Authorization header
`403`	Forbidden	Valid API key but insufficient permissions for this endpoint
`404`	Not Found	The requested resource (company, endpoint) does not exist
`429`	Too Many Requests	Rate limit exceeded. Check X-RateLimit headers for reset time
`500`	Internal Server Error	Server error. Retry the request or contact support

Response Format

All successful responses return JSON with a consistent structure:

{
  "company_name": "Apple Inc.",
  "ticker": "AAPL",
  "cik": "0000320193",
  "data": [
    {
      "period_end": "2024-09-30",
      "period_type": "quarterly",
      // ... endpoint-specific fields
    }
  ],
  "count": 4,
  "has_more": false
}

Common Response Fields:

company_name - Full company name
ticker - Stock ticker symbol
cik - SEC Central Index Key
data - Array of financial data objects
count - Number of records returned
has_more - Whether more data is available (pagination)

Ready to make your first API call?

Start with the Universe endpoint to discover available companies, or jump straight to financial data.

Universe Endpoint Income Statement