API Reference

Authentication

Every endpoint takes the same header. Base URL:

https://gateway.drillr.ai/api/v2

curl -H "X-API-KEY: $DRILLR_API_KEY" \
  "https://gateway.drillr.ai/api/v2/tickers?query=Apple%20Inc.&market=US"

No key yet? Create one under API Keys — it is shown once, so store it where your shell can read it. Connecting an agent over MCP instead? That signs in through the browser and needs no key at all.

Conventions

• One ticker identifies both the company and its market. Data endpoints take a ticker parameter and need nothing else to know which market to read; there is no separate market switch. Use /tickers to turn a name, code or identifier into the ticker Drillr expects, and /company-discovery when you only have a description. Both can be narrowed to one market with the optional market filter.
• Dates are YYYY-MM-DD and ranges are inclusive at both ends. An endpoint that uses a different axis, such as a reporting month, says so on its page.
• Paging exists only on endpoints that list a page parameter. Pages start at 1; a page shorter than limit is the last one.
• No numeric filters. Endpoints do not filter by amount; fetch the rows and filter them on your side.

Rate limits

100 requests per key per minute. Beyond that the request returns 429 rate_limit_exceeded with retry_after_seconds in the body; a 429 is not billed.

Errors

Every error is { "error", "message" } with error one of bad_request, unauthenticated, insufficient_credits, not_found, rate_limit_exceeded, internal_error, service_unavailable. Requests fail closed: an out-of-coverage ticker returns 404, while an invalid discovery-market value or unknown parameter returns 400. Nothing is silently dropped, and errors are not billed.

Endpoints

Grouped by what they answer. Each endpoint has its own page with parameters, fields and a worked example.

REST and MCP draw from the same credits wallet. Requests rejected before data retrieval are not charged; see Pricing for plans and current credit options.