drillr.ai
API keys →

API Reference

v2spec r115

REST endpoints over the same tables the drillr app runs on. Pass query parameters (news search takes a JSON body), get a JSON data array back; every row that came out of a filing links to that filing. One API for the US, China and Japan.

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.

Company

  • Ticker resolution

    Converts a name, code, ISIN, CIK or CUSIP into the ticker used by every other endpoint; without query, lists all trading stocks in a market

  • Company discovery

    Finds companies from a natural-language description and returns the ticker, name and match reason; the entry point when the ticker is unknown

  • Company profile

    Basic company profile: name, exchange, industry, listing date, website and headcount, one row per company

Filing Search

  • Filing list

    A company's filings with form type, filing date and a link to the official document, newest first, covering every form type in the window

  • Filing search

    Search SEC filings and Chinese and Japanese financial reports for facts beyond standard metrics, with original passages for verification

Signals

  • Industry inflections

    Industry changes synthesized from multiple companies' earnings calls, one row per theme, with mechanism, degree and per-company impact

  • Enterprise AI adoption

    Specific AI applications a company disclosed on earnings calls, one row per disclosure observation, linked across periods by application_id

  • News search

    Cross-source news search returning storylines, events and attributed claims, with summaries and links to the original articles

Events

  • Event timeline

    Company event timeline: financings, deals, executive changes, dividends and buybacks in one list, common fields only

  • Financing events

    Financing events with terms: equity / debt issuances, convertible notes, guarantees, defaults

  • Deals and agreements

    Deals and agreements: M&A, divestitures, joint ventures, licensing, material contracts, settlements, with counterparty and direction

  • Executive changes

    Executive, director and auditor changes: who, which role, appointed or departed

  • Corporate actions

    Corporate actions: dividends, buybacks, splits, stock dividends and capital reductions (historical data still being expanded)

  • Stake changes

    Major shareholder positions disclosed in SEC Schedule 13D/G filings and changes from the preceding filing

Ownership

Executives

  • Executive roster

    Executive roster: name, position and current status, with filing provenance, queried by company

  • Executive compensation

    Annual executive compensation: salary, bonus, stock and option awards and total (DEF 14A)

Financials

  • Income statement

    Income statement: revenue, profit and per-share data, one row per period

  • Balance sheet

    Balance sheet: assets, liabilities and equity, one row per period

  • Cash flow statement

    Cash flow statement: operating, investing and financing cash flows plus free cash flow, one row per period

  • Financial metrics snapshot

    Precomputed valuation and financial ratios: market cap, multiples, margins, returns, growth, leverage and liquidity, one row per ticker

Earnings

  • Earnings calendar

    Earnings calendar: announcement date, EPS / revenue estimates and actuals

  • Earnings call summary

    Structured earnings call summary: highlights, guidance, risks, segments and Q&A, without the transcript

Prices

Analyst

  • Analyst consensus

    Analyst consensus: five-tier rating distribution over the last 90 days plus mean / high / low price target, one row per ticker

  • Rating events

    Individual analyst rating / price target changes from news reports, with a link to the source article

Per-endpoint rates

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.

All other endpoints20 cr / thousand calls

0.02 cr per call. Every structured-data retrieval endpoint sits in this tier, and a multi-ticker request such as ticker=AAPL,MSFT still counts as 1 call

/filing-search100 cr / thousand calls

0.1 cr per call. A request counts as 1 call, regardless of hit count or how many markets are searched

/industry-inflections/enterprise-ai-adoption/news-search1 cr / call

Cross-company research and news search: results are extracted, deduplicated, and aggregated into storylines rather than fields passed straight through

/company-discovery3 cr / call

Natural-language semantic search; one request runs one vector search and ranking pass