Full-text search over filing content

POST

/api/b2b/search/filings

const url = 'https://api.stockalloy.com/api/b2b/search/filings';
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<X-API-Key>', 'Content-Type': 'application/json'},
  body: '{"query":"supply chain constraints","ticker":"AAPL","types":["risk","mda"],"after":"3y","limit":5}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.stockalloy.com/api/b2b/search/filings \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "query": "supply chain constraints", "ticker": "AAPL", "types": [ "risk", "mda" ], "after": "3y", "limit": 5 }'

BM25 full-text search over chunked SEC filing content (MD&A, notes, risk factors, tables, and more). Company-scoped by default; cross-company search requires at least 2 query terms and the cross-company entitlement on your key. Single-term company-scoped queries are automatically limited to the last 3 years unless you pass after.

Authorizations

ApiKeyAuth

Request Body^required

application/json

object

ticker

Stock ticker, e.g. DECK.

string

cik

Zero-padded 10-digit SEC CIK, e.g. 0001011570.

string

tickers

Company set (search endpoints only).

Array<string>

ciks

Company set (search endpoints only).

Array<string>

query

required

string

types

Restrict to specific filing section chunk types.

Array<string>

Allowed values: mda notes business risk legal properties market_risk controls compliance table_context

after

YYYY-MM-DD, a relative window (1y…50y), or all for no date floor.

string

before

YYYY-MM-DD.

string

legal

Expand legal-domain phrases (going concern, material weakness, covenants, …) into the query.

boolean

sort

Default recent for company-scoped search; cross-company search always sorts by relevance.

string

Allowed values: recent relevance

limit

Max 50 company-scoped, max 25 cross-company.

integer

default: 10 >= 1 <= 50

include_series

Also return related metric series suggestions.

boolean

series_limit

integer

default: 6 >= 1 <= 12

min_confidence

Minimum section-classification confidence. Cross-company search enforces at least 0.5.

number

<= 1

Example

{
  "query": "supply chain constraints",
  "ticker": "AAPL",
  "types": [
    "risk",
    "mda"
  ],
  "after": "3y",
  "limit": 5
}

Responses

200

Ranked filing chunks with snippets and viewer links.

application/json

object

scope

string

Allowed values: company company_set cross_company

ticker

string | null

cik

string | null

tickers

Array<string> | null

ciks

Array<string> | null

query

string

legal_mode

boolean

expanded_terms

Array<string>

sort

string

Allowed values: recent relevance

series_suggestions

Present when include_series: true and matches exist.

object

series

Array<object>

object

key

additional properties

any

applied_filed_at_after

string | null

applied_filed_at_before

string | null

applied_filed_at_after_reason

Why a date floor was applied, e.g. auto_one_term_recent_3y or explicit_relative_3y.

string

results

Array<object>

object

chunk_id

string

result_key

string | null

cik

string

ticker

string | null

current_ticker

string | null

company_name

string | null

accession

string

source_accession

string

form_type

string | null

source_form_type

string | null

filed_at

string | null

source_filed_at

string | null format: date

chunk_type

string

confidence

number

rank_mode

string

Allowed values: recent relevance

score

BM25 score — lower is better.

number

part

string | null

item

string | null

note

string | null

heading

string | null

snippet_preview

string | null

snippet_text

string | null

viewer_url

Opens the filing with the matched passage highlighted.

string | null

html_offset_start

integer | null

html_offset_end

integer | null

html_start_offset

integer | null

html_end_offset

integer | null

manual_review

object

status

string

Allowed values: verified rejected needs_review

reviewer

string | null

note

string | null

reviewed_at

string | null

is_fresh

boolean

Example

{
  "scope": "company",
  "sort": "recent",
  "results": [
    {
      "rank_mode": "recent",
      "manual_review": {
        "status": "verified"
      }
    }
  ]
}

Headers

X-RateLimit-Limit

integer

Requests allowed per minute for this key.

X-RateLimit-Remaining

integer

Requests remaining in the current minute window.

X-RateLimit-Reset

integer

Unix timestamp (seconds) when the window resets.

400

Invalid request — missing/invalid fields, malformed JSON, or an unsupported scope combination.

application/json

object

error

required

Human-readable error message.

string

Example

{
  "error": "query is required"
}

401

Missing or invalid API key.

application/json

object

error

required

Human-readable error message.

string

Example

{
  "error": "API key required"
}

403

Key revoked/disabled/expired, account disabled, key not entitled for this product, or cross-company search not enabled for this key.

application/json

object

error

required

Human-readable error message.

string

Example

{
  "error": "API key has expired"
}

404

Company not found (unknown ticker or CIK).

application/json

object

error

required

Human-readable error message.

string

Example

{
  "error": "Unknown ticker: ZZZZ"
}

429

Rate limit exceeded (per-minute) or quota exceeded (daily/monthly, account-level or per-key). Distinguish by body shape.

application/json

One of:

object
object

object

error

required

string

Allowed value: Rate limit exceeded

retryAfter

required

Seconds until the window resets.

integer

limit

required

Requests allowed per minute for this key.

integer

windowMs

required

integer

Allowed value: 60000

object

error

required

daily quota exceeded or monthly quota exceeded.

string

quota

required

string

Allowed values: daily monthly

scope

required

account sums usage across all keys on the account; api_key is a per-key cap.

string

Allowed values: account api_key

limit

required

integer

used

required

integer

Examples

Per-minute rate limit

{
  "error": "Rate limit exceeded",
  "retryAfter": 31,
  "limit": 60,
  "windowMs": 60000
}

Monthly quota

{
  "error": "monthly quota exceeded",
  "quota": "monthly",
  "scope": "account",
  "limit": 5000,
  "used": 5000
}

Headers

X-RateLimit-Limit

integer

Requests allowed per minute for this key.

X-RateLimit-Remaining

integer

Requests remaining in the current minute window.

X-RateLimit-Reset

integer

Unix timestamp (seconds) when the window resets.

Retry-After

integer

Seconds to wait before retrying (429 only).

500

Unexpected server error.

application/json

object

error

required

Human-readable error message.

string

Example

{
  "error": "Facts lookup failed"
}

503

The verified-facts backend is temporarily unavailable. Transient — retry with backoff. This is an infrastructure condition, not a data gap.

application/json

object

error

required

Human-readable error message.

string

Example

{
  "error": "Facts backend unavailable"
}

Full-text search over filing content

Authorizations

Request Bodyrequired

Example

Responses

200

Example

Headers

400

Example

401

Example

403

Example

404

Example

429

Examples

Headers

500

Example

503

Example

Request Body^required