# Marked

> Marked is an agent-friendly REST API and MCP server providing structured
> financial data for Indian capital markets, built for AI agents, research
> tools and financial applications.

Marked covers 9,400+ listed Indian companies with 1.3M+ financial facts and
29K+ filings and disclosures, normalized across sources and served as
structured JSON. Every financial value carries the filing it came from.

## Base URL

https://app.marked.run

## Authentication

Include your API key in the `X-API-Key` header with every request.
`Authorization: Bearer <key>` is also accepted.

**There is no self-serve signup.** No endpoint creates an account, and no
agent can issue itself a key. Keys are issued per workspace by the Marked
team: ask at access@marked.run or from https://marked.run

A key looks like `mk_live_...`, is shown once at issue, and only its hash is
stored. API requests and MCP tool calls draw on the same monthly allowance.
Responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`;
over the limit, requests answer `429` and are not billed.

## API Endpoints

### Discovery
- Index: GET /v1/ — every endpoint, plus the row count and freshness of each dataset. No parameters.

### Financials
- Financial statements: GET /v1/financials
  - `ticker` (required), `period` (annual|quarterly), `basis` (consolidated|standalone), `concept`, `as_of`, `limit`
- Derived metrics: GET /v1/financial-metrics
  - `ticker` (required), `period`, `basis`, `as_of`
  - Ratios and growth rates computed from the canonical facts, not restated separately.

### Companies
- Company master: GET /v1/companies
  - `q`, `sector`, `listing_status`, `limit`, `offset`
  - Name matching is case-insensitive: `reliance`, `RELIANCE` and `Reliance Industries Ltd` resolve to the same company.

### Ownership
- Shareholding patterns: GET /v1/shareholding
  - `ticker` (required), `period_end`, `holders`, `limit`

### Filings and events
- Filings and disclosures: GET /v1/filings
  - `ticker`, `type`, `fiscal_year`, `start`, `end`, `limit`, `offset`
- Corporate actions: GET /v1/corporate-actions
  - `ticker`, `type`, `start`, `end`, `limit`, `offset`
  - Dividends, splits, bonuses and buybacks, from official typed dates.
- Corporate events: GET /v1/events
  - `ticker`, `type`, `types`, `start`, `end`, `limit`, `offset`

### Market data
- Prices: GET /v1/prices
  - `ticker` (required), `exchange`, `interval`, `start`, `end`, `latest`, `limit`
- Instruments: GET /v1/instruments
  - `ticker`, `exchange`, `segment`, `type`, `isin`, `company`, `limit`

### Search and research
- Search: POST /v1/search
  - body: `query` (required), `kinds`, `ticker`, `limit`
- Structured query: POST /v1/query
  - body: `query` (required), `plan`, `limit`
- Research question: POST /v1/ask
  - body: `query` (required), `session` (required), `limit`
  - A question in plain language. Returns an answer with the facts it rests on.

### Provenance
- Fact provenance: GET /api/v1/companies/{reference}/financials/{concept_id}/provenance
  - Every observation ever published for one number, each with its filing, oldest first. This is the "show me the primary source" answer.

## MCP Server

- Server: https://app.marked.run/mcp/ (streamable HTTP, trailing slash required)
- Auth: `X-API-Key` header. Marked does not use OAuth.
- 19 tools: `search`, `get_company`, `get_quote`, `get_historical_prices`,
  `get_financials`, `get_financial_history`, `screen_companies`,
  `list_screen_metrics`, `get_shareholding`, `get_corporate_actions`,
  `get_events`, `list_event_types`, `get_insider_activity`, `search_filings`,
  `get_filing`, `get_earnings`, `query`, `get_fact_provenance`,
  `list_datasets`

## How Marked resolves conflicting data

When two sources report the same company, concept, period and basis
differently, Marked returns one canonical answer chosen by source quality:
structured XBRL over a scraped PDF, exchange over investor relations, most
recently known as the final tiebreak. Never by whichever row was written
first. Values that cannot be attributed to a reporting period are withheld
from answers rather than guessed at. Nothing is discarded: the full
observation trail stays available through the provenance endpoint.

## AI Agent Resources

- **Agent onboarding**: https://marked.run/agents.md — connect a client and run a first query
- **Pricing**: https://marked.run/#pricing — Developer 2,000, Builder 25,000, Scale 500,000 requests/month; Enterprise uncapped
- **Console**: https://app.marked.run/dashboard — keys and usage
- **Sign in**: https://app.marked.run/login

## Links

- [Marked](https://marked.run)
- [Support](mailto:access@marked.run)