GET /v3/companies/{cik_or_ticker}/periods
Get one concept by fiscal period.
Reported quarters, halves, nine months, and years are served as filed, as known at as_of. Periods not reported are derived: Q4 = FY - 9M, H2 = FY - H1, Q3 = 9M - H1, and Q2 = H1 - Q1. A derived value shows its formula, inputs, and rule version. TTM (trailing twelve months) is the sum of four quarters in a row. Fiscal labels come from the company's own dates.
API key: required. See Authentication.
Group: Financial data (XBRL)
Try it
import os
import requests
r = requests.get(
"https://api.secblast.com/v3/companies/AAPL/periods",
params={"concept": "us-gaap:Revenues"},
headers={"Authorization": f"Bearer {os.environ['SECBLAST_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
print(r.json())Response
Nothing has been sent yet.
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
cik_or_ticker | path | string | yes | The company's CIK, such as 320193, or its ticker, such as AAPL. Leading zeros are optional. A ticker is looked up in SEC's ticker file, in any letter case. An unknown ticker is a 400 unknown_ticker error. The resolved member gives the CIK. | |
concept | query | string | yes | Concept as prefix:LocalName, such as us-gaap:Revenues. Required. | |
unit | query | string | no | Only this unit, such as iso4217:USD, shares, or iso4217:USD/shares. | |
dims | query | string | no | Dimensions: none (default, no dimensions) or a dims_hash (32 hex digits) for one exact set. | |
as_of | query | string | no | Point in time: each value as known from filings accepted by then. YYYY-MM-DDTHH:MM:SSZ in UTC (add up to 6 decimals for an exact time), or YYYY-MM-DD for the whole UTC day. |
Details
Derivation rules: a value is derived only when its inputs are on the same basis at as_of. Otherwise the status is basis_mismatch, with no number and the first-reported value beside it (first_reported). Per-share values, share counts, and instants are never derived. TTM inherits a quarter's refusal. Deleted filings are not read and are listed in excluded. An original counts again when its amendment is withdrawn. A derived value that used a deleted filing is not served until it is rebuilt.
Responses
| Status | Body | Description |
|---|---|---|
200 | XbrlCompanyPeriods (application/json) | OK |
400 | Problem (application/problem+json) | Invalid or unknown parameter. |
401 | Problem (application/problem+json) | Missing, invalid, or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). |
503 | Problem (application/problem+json) | Database unavailable; retry after the Retry-After delay. |
default | Problem (application/problem+json) | Any other error (405, 500, 504). |
Response body
A 200 carries a XbrlCompanyPeriods object.
| Field | Type | Required | Description |
|---|---|---|---|
as_of | string | null | yes | |
cik | string | yes | |
concept | string | yes | |
data | array of object | yes | |
derivation | object | yes | Whether values of this concept can be added over time. additivity is flow, per_share, share_count, ratio, or stock. Only a flow can be computed for missing periods; for the others derived is false, with the reason in status. |
dims | string | yes | |
excluded | Excluded | yes | |
excluded_total | integer | yes | |
has_more | boolean | yes | |
next_cursor | null | yes | |
rule | string | yes | |
rule_version | string | yes |
Example request
import os
import requests
r = requests.get(
"https://api.secblast.com/v3/companies/AAPL/periods",
params={"concept": "us-gaap:Revenues"},
headers={"Authorization": f"Bearer {os.environ['SECBLAST_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
print(r.json())Example answer
import os
import requests
r = requests.get(
"https://api.secblast.com/v3/companies/AAPL/periods",
params={"concept": "us-gaap:Revenues"},
headers={"Authorization": f"Bearer {os.environ['SECBLAST_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
print(r.json()){
"as_of": null,
"cik": "0000320193",
"concept": "us-gaap:Revenues",
"data": [
{
"accession": "0000320193-18-000145",
"decimals": "-6",
"fact_seq": 1112,
"filing": {
"accepted_at": "2018-11-05T18:01:40Z",
"filing_date": "2018-11-05",
"form_type": "10-K"
},
"fiscal_period": "Q4",
"fiscal_year": 2018,
"flags": [
"fiscal_year_changed"
],
"period": {
"class": "quarter",
"days": 91,
"durp_days": 0,
"end": "2018-09-29",
"start": "2018-07-01"
},
"source": "reported",
"status": "ok",
"unit_norm": "iso4217:USD",
"value": "62900000000",
"value_raw": "62900000000"
},
{
"accession": "0000320193-18-000145",
"decimals": "-6",
"fact_seq": 1113,
"filing": {
"accepted_at": "2018-11-05T18:01:40Z",
"filing_date": "2018-11-05",
"form_type": "10-K"
},
"fiscal_period": "FY",
"fiscal_year": 2018,
"flags": [
"fiscal_year_changed"
],
"period": {
"class": "year",
"days": 364,
"durp_days": -1,
"end": "2018-09-29",
"start": "2017-10-01"
},
"source": "reported",
"status": "ok",
"unit_norm": "iso4217:USD",
"value": "265595000000",
"value_raw": "265595000000"
}
],
"derivation": {
"additivity": "flow",
"derived": true
},
"dims": "none",
"excluded": [],
"excluded_total": 0,
"has_more": false,
"next_cursor": null,
"rule": "Q4 = FY - 9M only when both are on the same basis at as_of; otherwise basis_mismatch, no number, and the first-reported Q4 beside it. Both operands re-reported on the new basis derive again. The same for H2 = FY - H1, Q3 = 9M - H1, Q2 = H1 - Q1. Per-share values, share counts, and instants are never…(truncated)",
"rule_version": "periods-1.3",
"resolved": {
"cik": "0000320193",
"ticker": "AAPL",
"ticker_file_date": "2026-11-18"
}
}More in Financial data (XBRL)
Previous: GET /v3/companies/{cik_or_ticker}/income-statement · Next: GET /v3/companies/{cik_or_ticker}/segments
Markdown version: /docs/reference/get-companies-cik-or-ticker-periods.md