SEC EDGAR via Scavio

Resolve a ticker or company name to its CIK, then read the filer's profile, page its filings, pull the full reported history of any XBRL concept, list every concept it reports, and run EDGAR full-text search back to 2001. All six endpoints return structured JSON.

When to trigger

Use this skill when the user asks to:

• Find a company's CIK from a ticker or name
• List a company's SEC filings, filtered by form type or date
• Pull a reported financial number over time (revenue, net income, EPS) straight from XBRL
• Discover which financial concepts a filer actually reports
• Search the full text of SEC filings for a phrase, a risk factor, or a named party
• Check a filer's SIC industry, EIN, LEI, state of incorporation or fiscal year end
• Build investment research, fundamentals datasets, or filing-monitoring pipelines

Setup

Get a free API key at scavio.dev (50 free credits to get started, no card required):

export SCAVIO_API_KEY=sk_live_your_key

If you do not have a key yet

An agent running this skill without SCAVIO_API_KEY set will get 401 on every call below. The whole path from nothing to a working key is self-serve:

1. Sign up at dashboard.scavio.dev - email or Google, no card required.
2. A key is created for the account automatically at signup. It is on the dashboard under API Keys, ready to copy.
3. A new account starts with 50 credits. Endpoints in this skill cost 1 credit each unless the table below says otherwise.

When the balance runs out the API answers 402 with a JSON body carrying billing_url. Topping up needs no code change - the same key keeps working. The smallest purchase is 2,500 credits for $25, and monthly plans work out cheaper per credit if the usage is steady rather than one-off.

Every request is a POST with a JSON body and:

Authorization: Bearer $SCAVIO_API_KEY

Endpoints

Base URL: https://api.scavio.dev. All paths are under /api/v1/sec. Every endpoint costs 1 credit.

This runs on the SEC's own free JSON API, so the data is first-party.

Workflow

Look up first. Callers hold a ticker (AAPL); EDGAR is keyed by CIK (0000320193).

1. Resolve: call /sec/lookup with query - a ticker, a company name, or a fragment. Each row carries its match tier as match, plus ready-made submissions, company-facts and EDGAR URLs.
2. Profile: call /sec/company with the cik (or a ticker - both fields accept either spelling, which softens the lookup step but does not remove it).
3. Filings: call /sec/filings with cik or ticker, filtered by form and dates.
4. Financials, in two steps: call /sec/facts to discover which XBRL tags the filer actually reports, then /sec/concept with one of those tags to pull its full reported history.
5. Full text: call /sec/search to find the documents that mention a phrase, across all filers.

/sec/lookup, /sec/company, /sec/concept and /sec/facts do not paginate. /sec/filings and /sec/search do.

Pagination

• /sec/filings - page (1-based) with limit (1-500, default 50).
• /sec/search - page, capped at 100, 100 documents per page. The index refuses a result window past 10,000, which is where the cap comes from.
• limit on /lookup, /concept and /facts sizes the response. It is not a page parameter and there is no second page.

Parameters

Lookup (/lookup)

Filers the SEC lists with no exchange at all are excluded by any exchange value - omit it if you might be chasing an OTC or unlisted filer.

Company (/company)

cik or ticker is required.

Filings (/filings)

cik or ticker is required.

Concept (/concept)

cik or ticker is required.

Facts (/facts)

cik or ticker is required.

Search (/search)

/search accepts no query at all - a cik, ticker, form or date filter on its own is a valid search.

Examples

import requests

BASE = "https://api.scavio.dev"
# Your key from https://scavio.dev. Load it from your environment or secret
# store in real code - keep it out of source control.
API_KEY = "sk_your_key_here"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Resolve the ticker to a CIK - always start here
hits = requests.post(f"{BASE}/api/v1/sec/lookup", headers=HEADERS,
    json={"query": "AAPL"}).json()

# 2. Filer profile
company = requests.post(f"{BASE}/api/v1/sec/company", headers=HEADERS,
    json={"ticker": "AAPL"}).json()

# 3. Annual reports only - note this also brings back 10-K/A amendments
filings = requests.post(f"{BASE}/api/v1/sec/filings", headers=HEADERS,
    json={"ticker": "AAPL", "form": "10-K", "date_from": "2015-01-01", "limit": 100}).json()

# 4. Financials in two steps: discover the tag, then pull its history
facts = requests.post(f"{BASE}/api/v1/sec/facts", headers=HEADERS,
    json={"ticker": "AAPL", "query": "revenue"}).json()

revenue = requests.post(f"{BASE}/api/v1/sec/concept", headers=HEADERS,
    json={"ticker": "AAPL", "concept": "RevenueFromContractWithCustomerExcludingAssessedTax",
          "taxonomy": "us-gaap", "unit": "USD"}).json()

# 5. Full-text search across all filers, 2001-today
mentions = requests.post(f"{BASE}/api/v1/sec/search", headers=HEADERS,
    json={"query": "\"material weakness\"", "form": "8-K",
          "date_from": "2024-01-01", "sort": "newest", "page": 1}).json()

Response shapes

Every response uses the envelope { data, response_time, credits_used, credits_remaining }.

• lookup - matching filers with symbol, listing exchange, and ready-made submissions / company-facts / EDGAR URLs, tiered by match quality; each row carries its tier as match.
• company - legal and former names, SIC industry, filer category, EIN, LEI, state of incorporation, fiscal year end, business and mailing addresses, every ticker with its exchange, which forms it files and how often, plus a preview of its 10 most recent filings.
• filings - accession number, form and root form, filing and period dates, 8-K item codes, direct links to the primary document, the filing index and the attachment directory. history_truncated is set when include_history hit the 10-shard cap.
• concept - every value the filer reported for that concept, newest period first, with the form and filing each number came from. Restatements are kept, not collapsed, and latest disambiguates a quarter from its year-to-date twin using the SEC's comparability flag.
• facts - every XBRL concept the filer reports: tag, label, description, units and most recent value, across us-gaap, dei and any other taxonomy it uses.
• search - each hit is the matching document with its URL, form, filing date and filer identity, plus facets breaking the whole result set down by company, form, industry and state.

Guardrails

• Every call is 1 credit, including include_history, which can do up to 10 lookups for that one credit. Use it rather than paging blindly into the past.
• XBRL tags are case-sensitive. netincomeloss is a 404 upstream, not a fuzzy match. Never guess a tag - call /sec/facts and use one it actually reports.
• form behaves differently on two endpoints. On /filings it matches the form and its root form, so 10-K also returns 10-K/A amendments (ask for 10-K/A to get amendments only). On /concept it is an exact match, so 10-K excludes 10-K/A. Do not carry an assumption from one to the other.
• EDGAR's "recent" block is not a fixed window - it can be a decade for a quiet filer and about a year for a prolific one. Never tell the user "this is everything" from a default /filings call; set include_history and check history_truncated.
• Full-text search coverage starts in 2001. A phrase absent from /search results is not proof it was never filed.
• Restatements are preserved in /concept. If you report a single number for a period, say which filing it came from.
• ticker wins over cik when both are sent - do not send a mismatched pair and expect the CIK to be honoured.
• Never fabricate CIKs, accession numbers, filing dates or reported figures. Only return API data, and cite the filing behind any number you quote.
• This is public regulatory data, not investment advice. Do not present a figure as a recommendation.

Failure handling

• 400 means an invalid or missing parameter - e.g. neither cik nor ticker, or a malformed date. Fix and retry.
• 401 means the API key is invalid or missing. Check SCAVIO_API_KEY.
• 404 usually means the CIK, the concept tag or the taxonomy does not exist upstream. Re-resolve with /lookup or /facts rather than retrying the same value.
• 429 means rate or usage limit exceeded. Wait before retrying. See rate limits.
• 502 / 503 mean upstream is temporarily unavailable - wait a few seconds and retry.
• If /search returns nothing, remember coverage starts in 2001 and try a looser phrase or a wider date range.
• If SCAVIO_API_KEY is not set, prompt the user to export it before continuing.

Python SDK

langchain-scavio has no SEC EDGAR tool - use the Scavio SDK directly:

pip install scavio==0.15.0

from scavio import ScavioClient

client = ScavioClient()  # reads SCAVIO_API_KEY

hits = client.sec.lookup("AAPL")
company = client.sec.company(ticker="AAPL")
filings = client.sec.filings(ticker="AAPL", form=["10-K", "10-Q"], include_history=True)
facts = client.sec.facts(ticker="AAPL", query="revenue")
history = client.sec.concept("NetIncomeLoss", ticker="AAPL", taxonomy="us-gaap")
docs = client.sec.search(query='"material weakness"', form="8-K", sort="newest")

JavaScript / TypeScript:

npm install scavio@0.15.0

import { Scavio } from "scavio";

const scavio = new Scavio(); // reads SCAVIO_API_KEY
const hits = await scavio.sec.lookup({ query: "AAPL" });
const history = await scavio.sec.concept({ ticker: "AAPL", concept: "NetIncomeLoss" });