Tutorial: SEC EDGAR - Gnist Context

Business

Data source: SEC EDGAR

Overview

SEC EDGAR wraps SEC EDGAR, handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-sec-edgar": {
      "url": "https://context.gnist.ai/mcp/sec-edgar/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`search_filings`

Full-text search over all public SEC filings (10-K, 10-Q, 8-K, proxy, and more). Args: query: Search terms — phrase-matched against filing text. Examples: "artificial intelligence", "climate risk", "supply chain". form_type: Filter to a specific form type: "10-K", "10-Q", "8-K", "DEF 14A". Omit to search all form types. company: Filter by company name (partial match). date_from: Earliest filing date — YYYY-MM-DD. date_to: Latest filing date — YYYY-MM-DD. max_results: Maximum filings to return (1–100, default 20). Returns: List of matching filings with accession number, form type, filing date, company name, reporting period, and EDGAR viewer URL.

Parameter	Type	Required	Description
`query`	string	required	Search terms — phrase-matched against filing text.
`form_type`	any	optional
`company`	any	optional
`date_from`	any	optional
`date_to`	any	optional
`max_results`	integer	optional	(default: `20`)

curl -X POST "https://context.gnist.ai/mcp/sec-edgar/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_filings", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/sec-edgar/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'},
            'name': 'search_filings'}},
)
print(resp.json())

`get_company_filings`

Retrieve recent SEC filings for any public company by ticker or CIK. Args: ticker_or_cik: Company identifier — either a ticker symbol (e.g. "AAPL", "MSFT") or a numeric CIK (e.g. "320193" or "0000320193"). form_type: Filter to a specific form type: "10-K", "10-Q", "8-K", etc. Omit to return all recent filings. limit: Maximum filings to return (default 10). Returns: Company metadata (name, CIK, ticker, industry) and a list of filings, each with accession number, form type, dates, and document URL.

Parameter	Type	Required	Description
`ticker_or_cik`	string	required	Company identifier — either a ticker symbol (e.g. "AAPL", "MSFT") or a numeric CIK (e.g. "320193" or "0000320193").
`form_type`	any	optional	Filter to a specific form type: "10-K", "10-Q", "8-K", etc. Omit to return all recent filings.
`limit`	integer	optional	Maximum filings to return (default 10). (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/sec-edgar/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_company_filings", "arguments": {"ticker_or_cik": "AAPL"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/sec-edgar/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'ticker_or_cik': 'AAPL'},
            'name': 'get_company_filings'}},
)
print(resp.json())

`get_financial_facts`

Retrieve XBRL-tagged financial data for a company concept across all reporting periods. Common concepts (us-gaap taxonomy): - Revenue: "Revenues" or "RevenueFromContractWithCustomerExcludingAssessedTax" - Net income: "NetIncomeLoss" - Total assets: "Assets" - Cash: "CashAndCashEquivalentsAtCarryingValue" - EPS (basic): "EarningsPerShareBasic" (use unit="USD/shares") Args: ticker_or_cik: Ticker symbol (e.g. "AAPL") or numeric CIK (e.g. "320193"). concept: XBRL concept tag name. Case-sensitive, CamelCase. unit: Unit of measure — "USD", "shares", or "USD/shares". Default "USD". taxonomy: XBRL taxonomy — "us-gaap" (default) or "dei". Returns: Company name, concept label, and a list of facts sorted newest-first.

Parameter	Type	Required	Description
`ticker_or_cik`	string	required	Ticker symbol (e.g. "AAPL") or numeric CIK (e.g. "320193").
`concept`	string	required	XBRL concept tag name. Case-sensitive, CamelCase.
`unit`	string	optional	Unit of measure — "USD", "shares", or "USD/shares". Default "USD". (default: `USD`)
`taxonomy`	string	optional	XBRL taxonomy — "us-gaap" (default) or "dei". (default: `us-gaap`)

curl -X POST "https://context.gnist.ai/mcp/sec-edgar/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_financial_facts", "arguments": {"ticker_or_cik": "AAPL", "concept": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/sec-edgar/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'concept': 'example', 'ticker_or_cik': 'AAPL'},
            'name': 'get_financial_facts'}},
)
print(resp.json())

`get_filing_section`

Extract a specific section from a public SEC filing as plain text. Args: accession_number: EDGAR accession number — e.g. "0000320193-23-000106". section: Section to extract. Named sections: "business", "risk_factors", "mda", "financial_statements", "executive_compensation", "quantitative_risk", "controls". Also accepts raw item numbers: "1", "1A", "7", "7A", "8", "9A", "11". Returns: Section name, source URL, and extracted plain text (up to ~8000 chars).

Parameter	Type	Required	Description
`accession_number`	string	required	EDGAR accession number — e.g. "0000320193-23-000106".
`section`	string	required	Section to extract. Named sections: "business", "risk_factors", "mda", "financial_statements", "executive_compensation", "quantitative_risk", "controls". Also accepts raw item numbers...

curl -X POST "https://context.gnist.ai/mcp/sec-edgar/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_filing_section", "arguments": {"accession_number": "0000320193-23-000106", "section": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/sec-edgar/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'accession_number': '0000320193-23-000106',
                          'section': 'example'},
            'name': 'get_filing_section'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/sec-edgar/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/sec-edgar/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_filings to find items, then get_company_filings to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

Date range filtering
Use date range parameters to narrow results to a specific time window. Dates are typically in YYYY-MM-DD format.

FAQ

What data does SEC EDGAR provide?

SEC filings — 10-K, 10-Q, 8-K, and other company disclosures. It exposes 5 tools: search_filings, get_company_filings, get_financial_facts, get_filing_section, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the SEC EDGAR API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.