Run a safe SEC API request

This page is a terminal playground, not an anonymous sandbox. Each call uses your account and can count toward its applicable usage limits. Start with the shown low limits while you validate response shapes.

Prerequisites

export SECAPI_API_KEY="secapi_..."

Keep the key out of shell history, browser code, and committed files.

1. Resolve an issuer

curl --include --fail-with-body \
  "https://api.secapi.ai/v1/entities/resolve?ticker=AAPL" \
  -H "x-api-key: $SECAPI_API_KEY"

Expect a successful response with the matched ticker and CIK, plus a Request-Id header. The exact response can contain additional fields.

{ "ticker": "AAPL", "cik": "0000320193" }

2. Retrieve one source filing

curl --fail-with-body \
  "https://api.secapi.ai/v1/filings/latest?ticker=AAPL&form=10-K" \
  -H "x-api-key: $SECAPI_API_KEY"

Record the returned accessionNumber, filingDate, and filingUrl. A “latest” result changes as the issuer files; use an accession-specific reference when you need an immutable document identity.

3. Inspect a compact response where supported

curl --fail-with-body \
  "https://api.secapi.ai/v1/filings/latest?ticker=AAPL&form=10-K&view=agent" \
  -H "x-api-key: $SECAPI_API_KEY"

view=agent is an endpoint-specific projection. It can omit envelope metadata that is present in the default response. Confirm its fields in the operation reference before using it for a citation or audit trail.

4. Explore filing workflows

# List up to three Apple 10-K filings.
curl --fail-with-body \
  "https://api.secapi.ai/v1/filings?ticker=AAPL&form=10-K&limit=3" \
  -H "x-api-key: $SECAPI_API_KEY"

# Read Item 1A from the latest Apple 10-K.
curl --fail-with-body \
  "https://api.secapi.ai/v1/filings/latest/sections/item_1a?ticker=AAPL&form=10-K" \
  -H "x-api-key: $SECAPI_API_KEY"

5. Search filing text

# Search the filing corpus by text and issuer.
curl --fail-with-body \
  "https://api.secapi.ai/v1/search/fulltext?q=revenue%20recognition&ticker=AAPL&limit=5" \
  -H "x-api-key: $SECAPI_API_KEY"

# Search semantically for an issuer-specific question.
curl --fail-with-body \
  "https://api.secapi.ai/v1/search/semantic?q=supply%20chain%20risk&ticker=AAPL&limit=5" \
  -H "x-api-key: $SECAPI_API_KEY"

Search results and ranking change as filings and indexes change. Preserve the filing identifiers and citations returned by the route when you use a result.

6. Try statements and ownership

# One annual balance-sheet, income-statement, and cash-flow bundle.
curl --fail-with-body \
  "https://api.secapi.ai/v1/statements/all?ticker=AAPL&period=annual&limit=1" \
  -H "x-api-key: $SECAPI_API_KEY"

# Recent normalized insider records for NVIDIA.
curl --fail-with-body \
  "https://api.secapi.ai/v1/insiders?ticker=NVDA&limit=10" \
  -H "x-api-key: $SECAPI_API_KEY"

# Institutional holdings for a manager by CIK.
curl --fail-with-body \
  "https://api.secapi.ai/v1/owners/13f?cik=0001067983&limit=10" \
  -H "x-api-key: $SECAPI_API_KEY"

Use a different interface

Interface	Equivalent starting point
JavaScript SDK	`client.resolveEntity`, `client.latestFiling`, and `client.allStatements`
Python SDK	`client.resolve_entity`, `client.latest_filing`, and `client.all_statements`
CLI	`secapi entities resolve`, `secapi filings latest`, and `secapi statements get`
Hosted MCP	`entities.resolve`, `filings.latest`, `sections.get`, and `statements.get`

Expected failures

curl --include "https://api.secapi.ai/v1/entities/resolve?ticker=AAPL"

Without the API-key header, expect 401 and an authentication error. For 429, read Retry-After and wait that interval. For validation and availability errors, keep the response body and Request-Id, then check Troubleshooting.

Production notes

Run requests from a backend, worker, or local development shell, never from a public frontend.
Set a client timeout and a bounded retry policy. Do not blindly retry writes.
Log the endpoint, status, Request-Id, and SECAPI-Version; do not log the API key or full sensitive payloads.

Read Libraries and SDKs for installation or MCP workflows for client setup. Use the API reference to verify parameters, endpoint-specific limits, and response schemas.

​Prerequisites

​1. Resolve an issuer

​2. Retrieve one source filing

​3. Inspect a compact response where supported

​4. Explore filing workflows

​5. Search filing text

​6. Try statements and ownership

​Use a different interface

​Expected failures

​Production notes