# 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](https://www.secblast.com/docs/authentication).

**Group:** [Financial data (XBRL)](https://www.secblast.com/docs/reference#financial-data-xbrl)

## Try it

Send this route from the page, signed in with your key, or from the [console](https://www.secblast.com/console).

## 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](https://www.secblast.com/docs/reference/schemas#schema-xbrlcompanyperiods) (`application/json`) | OK |
| `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. |
| `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-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](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. |
| `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). |

## Response body

A `200` carries a [XbrlCompanyPeriods](https://www.secblast.com/docs/reference/schemas#schema-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](https://www.secblast.com/docs/reference/schemas#schema-excluded) | yes |   |
| `excluded_total` | integer | yes |   |
| `has_more` | boolean | yes |   |
| `next_cursor` | null | yes |   |
| `rule` | string | yes |   |
| `rule_version` | string | yes |   |

## Example request

```python
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

```python
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())
```

```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`](https://www.secblast.com/docs/reference/get-companies-cik-or-ticker-income-statement) · Next: [`GET /v3/companies/{cik_or_ticker}/segments`](https://www.secblast.com/docs/reference/get-companies-cik-or-ticker-segments)
