Extraction Series
Return periodized counts and optional hits for cached langextract spans.
Tier: paid | Cache: cache-only | Playground: authenticated only | Contract: 1.0.0
When To Use It
Use these tools for curated extraction caches and premium language-model-backed filing evidence.
Request Examples
BASE_URL="${EDGAR_API_URL:-https://www.edgarparser.com}"
curl -sS -G "$BASE_URL/api/extractions/series" \
-H "Authorization: Bearer $EDGAR_API_KEY" \
--data-urlencode "ticker=AAPL" \
--data-urlencode "schema=operational_kpis"import os
import requests
base_url = os.getenv("EDGAR_API_URL", "https://www.edgarparser.com")
headers = {"Authorization": f"Bearer {os.environ['EDGAR_API_KEY']}"}
params = {
"ticker": "AAPL",
"schema": "operational_kpis"
}
response = requests.get(f"{base_url}/api/extractions/series", headers=headers, params=params, timeout=30)
response.raise_for_status()
data = response.json()Key Response Fields
| Field | Type | Why It Matters |
|---|---|---|
status | const "success" | Transport-level success indicator inside the JSON response. |
semantic_status | "ok" | "partial" | "empty" | "error" | null | Whether the response is semantically usable, partial, empty, or errored. |
coverage_status | "complete" | "partial" | "narrow" | "none" | null | Completeness signal; do not present partial or narrow coverage as complete. |
coverage_warning | string | null | Human-readable explanation of missing or ambiguous coverage. |
candidate_filings | array<object> | null | Extraction result field; inspect provenance and coverage before treating it as disclosed. |
candidate_filings_count | integer | Count field; use it to detect empty, partial, or unexpectedly broad output. |
filings_missing_cache | array<object> | Extraction result field; inspect provenance and coverage before treating it as disclosed. |
filings_missing_cache_count | integer | Count field; use it to detect empty, partial, or unexpectedly broad output. |
Response Fields To Inspect
schema_name, evidence spans, and source filing metadata for every extracted claim.- Coverage or cache-miss fields before treating missing rows as “not disclosed.”
- Confidence, provenance, and extraction timestamp fields when comparing periods.
Errors And Coverage
401or403: the API key is missing, expired, or not allowed to use this tier.429: retry after the rate-limit window, and prefer broader batch or series tools over repeated single-period calls.- This tool is cache-only; if the target filing is not warm, warm it through an allowed paid path before retrying.
- Paid or LLM-backed paths should be used only when cheaper fact, filing, table, or text tools cannot answer the question.
- Treat partial coverage, empty arrays, and warning fields as answer-quality signals even when HTTP status is
200.
Related Tools
Search Extractions, Filing Extractions, Concept Trend
Generated Reference
Contract
| Field | Value |
|---|---|
| Tool | get_extraction_series |
| Method | GET |
| Path | /api/extractions/series |
| Contract version | 1.0.0 |
| Schema fingerprint | sha256:9bae9be657743e78ebb1c5dc94e8e3fc0348a08ebb588c064a6b63807bc880f7 |
Parameters
| Name | Location | Required | Type | Notes |
|---|---|---|---|---|
ticker | query | yes | string | |
schema | query | yes | string | |
period_from | query | no | string | null | |
period_to | query | no | string | null | |
class | query | no | string | null | |
form_type | query | no | string | null | |
source | query | no | string | |
allow_stale | query | no | boolean | |
include_candidates | query | no | boolean | |
include_hits | query | no | boolean | |
limit_hits_per_period | query | no | integer |
Response Schema (200)
{
"additionalProperties": true,
"properties": {
"candidate_filings": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
]
},
"candidate_filings_count": {
"type": "integer"
},
"coverage_status": {
"anyOf": [
{
"enum": [
"complete",
"partial",
"narrow",
"none"
],
"type": "string"
},
{
"type": "null"
}
]
},
"coverage_warning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"filings_missing_cache": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"filings_missing_cache_count": {
"type": "integer"
},
"filings_with_cache_count": {
"type": "integer"
},
"query": {
"additionalProperties": true,
"type": "object"
},
"searched_periods": {
"items": {
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
"type": "array"
},
"semantic_status": {
"anyOf": [
{
"enum": [
"ok",
"partial",
"empty",
"error"
],
"type": "string"
},
{
"type": "null"
}
]
},
"series": {
"items": {
"additionalProperties": true,
"properties": {
"accession": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"form_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"hits": {
"items": {
"additionalProperties": true,
"properties": {
"accession": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"attributes": {
"additionalProperties": true,
"type": "object"
},
"char_end": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"char_start": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"class": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"extracted_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"filing_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"form_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"grounding_confidence": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"grounding_method": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"llm_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"llm_provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"period": {
"type": "string"
},
"period_end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"schema_name": {
"type": "string"
},
"schema_version": {
"type": "string"
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"ticker": {
"type": "string"
},
"validation_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"ticker",
"period",
"schema_name",
"schema_version"
],
"type": "object"
},
"type": "array"
},
"hits_count": {
"type": "integer"
},
"period": {
"type": "string"
},
"period_end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"quarter": {
"type": "integer"
},
"year": {
"type": "integer"
}
},
"required": [
"year",
"quarter",
"period",
"hits_count"
],
"type": "object"
},
"type": "array"
},
"stale_filings_count": {
"default": 0,
"type": "integer"
},
"stale_schema_versions": {
"items": {},
"type": "array"
},
"status": {
"const": "success",
"type": "string"
},
"total_hits_count": {
"type": "integer"
}
},
"required": [
"status",
"candidate_filings_count",
"filings_with_cache_count",
"filings_missing_cache_count",
"total_hits_count"
],
"type": "object"
}