KPIs and guidance

One reported metric or guide for a period, with the filing quote.

Routes

Base URL https://api.gloom.sh. Send a key with each call; the key's account needs a plan.

GET /v1/kpis/{symbol}

Cited filing operating metrics. Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. A from or to parameter selects the history price; asOf requires Basic or above. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.

Parameter: symbol
In: path, required
Type: string ^[A-Za-z0-9.:-]{1,32}$
Notes: Company symbol; normalized to uppercase.

Parameter: metric
In: query
Type: string ^[a-z0-9_]{1,80}$

Parameter: basis
In: query
Type: reported, adjusted, constant_currency, organic

Parameter: from
In: query
Type: date, YYYY-MM-DD
Notes: Valid calendar date (YYYY-MM-DD). from must be on or before to.

Parameter: to
In: query
Type: date, YYYY-MM-DD
Notes: Valid calendar date (YYYY-MM-DD). from must be on or before to.

Parameter: asOf
In: query
Type: date, YYYY-MM-DD
Notes: Valid calendar date (YYYY-MM-DD). from must be on or before to.

Parameter	In	Type	Notes
`symbol`	path, required	string `^[A-Za-z0-9.:-]{1,32}$`	Company symbol; normalized to uppercase.
`metric`	query	string `^[a-z0-9_]{1,80}$`
`basis`	query	`reported`, `adjusted`, `constant_currency`, `organic`
`from`	query	date, `YYYY-MM-DD`	Valid calendar date (YYYY-MM-DD). from must be on or before to.
`to`	query	date, `YYYY-MM-DD`	Valid calendar date (YYYY-MM-DD). from must be on or before to.
`asOf`	query	date, `YYYY-MM-DD`	Valid calendar date (YYYY-MM-DD). from must be on or before to.

Credits: 2 (lookup x2); 4 with from or to
Plans: Basic, Desk, Enterprise
asOf: Basic, Desk, Enterprise

GET /v1/guidance/{symbol}

Filing guidance ranges and revisions. Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. A from or to parameter selects the history price; asOf requires Basic or above. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.

Parameter: symbol
In: path, required
Type: string ^[A-Za-z0-9.:-]{1,32}$
Notes: Company symbol; normalized to uppercase.

Parameter: metric
In: query
Type: string ^[a-z0-9_]{1,80}$

Parameter: basis
In: query
Type: reported, adjusted, constant_currency, organic

Parameter: from
In: query
Type: date, YYYY-MM-DD
Notes: Valid calendar date (YYYY-MM-DD). from must be on or before to.

Parameter: to
In: query
Type: date, YYYY-MM-DD
Notes: Valid calendar date (YYYY-MM-DD). from must be on or before to.

Parameter: asOf
In: query
Type: date, YYYY-MM-DD
Notes: Valid calendar date (YYYY-MM-DD). from must be on or before to.

Parameter	In	Type	Notes
`symbol`	path, required	string `^[A-Za-z0-9.:-]{1,32}$`	Company symbol; normalized to uppercase.
`metric`	query	string `^[a-z0-9_]{1,80}$`
`basis`	query	`reported`, `adjusted`, `constant_currency`, `organic`
`from`	query	date, `YYYY-MM-DD`	Valid calendar date (YYYY-MM-DD). from must be on or before to.
`to`	query	date, `YYYY-MM-DD`	Valid calendar date (YYYY-MM-DD). from must be on or before to.
`asOf`	query	date, `YYYY-MM-DD`	Valid calendar date (YYYY-MM-DD). from must be on or before to.

Credits: 2 (lookup x2); 4 with from or to
Plans: Basic, Desk, Enterprise
asOf: Basic, Desk, Enterprise

Example response

Synthetic values, marked in meta. GET /v1/datasets/kpis-guidance/sample returns it with no key and no account.

json

{
  "data": {
    "symbol": "ILLUSTRATIVE",
    "status": "available",
    "asOf": "2026-09-30T12:00:00.000Z",
    "coverage": {
      "country": "US",
      "languages": [
        "en"
      ],
      "documents": 1,
      "observations": 3,
      "guidance": 0,
      "firstPeriod": "2026-09-30",
      "lastPeriod": "2026-09-30",
      "lastPublishedAt": "2026-09-30T12:00:00.000Z",
      "sourceKinds": [
        "filing"
      ],
      "conflicts": 0
    },
    "series": [
      {
        "key": "revenue",
        "metric": {
          "id": "revenue",
          "name": "Illustrative revenue",
          "sector": "general",
          "unit": "count",
          "definition": "Illustrative metric",
          "aliases": {},
          "favorable": "higher"
        },
        "unit": "count",
        "currency": null,
        "basis": "reported",
        "dimensions": {},
        "latest": {
          "id": "illustrative-fact-1",
          "symbol": "ILLUSTRATIVE",
          "metricId": "revenue",
          "metric": {
            "id": "revenue",
            "name": "Illustrative revenue",
            "sector": "general",
            "unit": "count",
            "definition": "Illustrative metric",
            "aliases": {},
            "favorable": "higher"
          },
          "period": {
            "start": "2026-07-01",
            "end": "2026-09-30",
            "kind": "quarter",
            "fiscalYear": 2026,
            "fiscalQuarter": 3,
            "label": "Q3 2026"
          },
          "value": 100,
          "unit": "count",
          "currency": null,
          "basis": "reported",
          "dimensions": {},
          "confidence": 1,
          "seriesKey": "revenue",
          "asOf": "2026-09-30T12:00:00.000Z",
          "supersedesId": null,
          "revision": 1,
          "current": true,
          "conflict": false,
          "evidence": [
            {
              "id": "illustrative-evidence-1",
              "documentId": "illustrative-document",
              "sourceId": "illustrative-filing",
              "sourceKind": "filing",
              "url": "https://example.invalid/illustrative-filing",
              "title": "ILLUSTRATIVE filing",
              "publishedAt": "2026-09-30T12:00:00.000Z",
              "country": "US",
              "language": "en",
              "quote": "ILLUSTRATIVE revenue was 100.",
              "quoteOffset": 0,
              "quoteSourceLength": 100,
              "quoteMatchMode": "exact",
              "confidence": 1
            }
          ]
        },
        "observations": [
          {
            "id": "illustrative-fact-1",
            "symbol": "ILLUSTRATIVE",
            "metricId": "revenue",
            "metric": {
              "id": "revenue",
              "name": "Illustrative revenue",
              "sector": "general",
              "unit": "count",
              "definition": "Illustrative metric",
              "aliases": {},
              "favorable": "higher"
            },
            "period": {
              "start": "2026-07-01",
              "end": "2026-09-30",
              "kind": "quarter",
              "fiscalYear": 2026,
              "fiscalQuarter": 3,
              "label": "Q3 2026"
            },
            "value": 100,
            "unit": "count",
            "currency": null,
            "basis": "reported",
            "dimensions": {},
            "confidence": 1,
            "seriesKey": "revenue",
            "asOf": "2026-09-30T12:00:00.000Z",
            "supersedesId": null,
            "revision": 1,
            "current": true,
            "conflict": false,
            "evidence": [
              {
                "id": "illustrative-evidence-1",
                "documentId": "illustrative-document",
                "sourceId": "illustrative-filing",
                "sourceKind": "filing",
                "url": "https://example.invalid/illustrative-filing",
                "title": "ILLUSTRATIVE filing",
                "publishedAt": "2026-09-30T12:00:00.000Z",
                "country": "US",
                "language": "en",
                "quote": "ILLUSTRATIVE revenue was 100.",
                "quoteOffset": 0,
                "quoteSourceLength": 100,
                "quoteMatchMode": "exact",
                "confidence": 1
              }
            ]
          }
        ]
      },
      {
        "key": "volume",
        "metric": {
          "id": "volume",
          "name": "Illustrative volume",
          "sector": "general",
          "unit": "count",
          "definition": "Illustrative metric",
          "aliases": {},
          "favorable": "higher"
        },
        "unit": "count",
        "currency": null,
        "basis": "reported",
        "dimensions": {},
        "latest": {
          "id": "illustrative-fact-2",
          "symbol": "ILLUSTRATIVE",
          "metricId": "volume",
          "metric": {
            "id": "volume",
            "name": "Illustrative volume",
            "sector": "general",
            "unit": "count",
            "definition": "Illustrative metric",
            "aliases": {},
            "favorable": "higher"
          },
          "period": {
            "start": "2026-07-01",
            "end": "2026-09-30",
            "kind": "quarter",
            "fiscalYear": 2026,
            "fiscalQuarter": 3,
            "label": "Q3 2026"
          },
          "value": 200,
          "unit": "count",
          "currency": null,
          "basis": "reported",
          "dimensions": {},
          "confidence": 1,
          "seriesKey": "volume",
          "asOf": "2026-09-30T12:00:00.000Z",
          "supersedesId": null,
          "revision": 1,
          "current": true,
          "conflict": false,
          "evidence": [
            {
              "id": "illustrative-evidence-2",
              "documentId": "illustrative-document",
              "sourceId": "illustrative-filing",
              "sourceKind": "filing",
              "url": "https://example.invalid/illustrative-filing",
              "title": "ILLUSTRATIVE filing",
              "publishedAt": "2026-09-30T12:00:00.000Z",
              "country": "US",
              "language": "en",
              "quote": "ILLUSTRATIVE volume was 200.",
              "quoteOffset": 0,
              "quoteSourceLength": 100,
              "quoteMatchMode": "exact",
              "confidence": 1
            }
          ]
        },
        "observations": [
          {
            "id": "illustrative-fact-2",
            "symbol": "ILLUSTRATIVE",
            "metricId": "volume",
            "metric": {
              "id": "volume",
              "name": "Illustrative volume",
              "sector": "general",
              "unit": "count",
              "definition": "Illustrative metric",
              "aliases": {},
              "favorable": "higher"
            },
            "period": {
              "start": "2026-07-01",
              "end": "2026-09-30",
              "kind": "quarter",
              "fiscalYear": 2026,
              "fiscalQuarter": 3,
              "label": "Q3 2026"
            },
            "value": 200,
            "unit": "count",
            "currency": null,
            "basis": "reported",
            "dimensions": {},
            "confidence": 1,
            "seriesKey": "volume",
            "asOf": "2026-09-30T12:00:00.000Z",
            "supersedesId": null,
            "revision": 1,
            "current": true,
            "conflict": false,
            "evidence": [
              {
                "id": "illustrative-evidence-2",
                "documentId": "illustrative-document",
                "sourceId": "illustrative-filing",
                "sourceKind": "filing",
                "url": "https://example.invalid/illustrative-filing",
                "title": "ILLUSTRATIVE filing",
                "publishedAt": "2026-09-30T12:00:00.000Z",
                "country": "US",
                "language": "en",
                "quote": "ILLUSTRATIVE volume was 200.",
                "quoteOffset": 0,
                "quoteSourceLength": 100,
                "quoteMatchMode": "exact",
                "confidence": 1
              }
            ]
          }
        ]
      },
      {
        "key": "subscribers",
        "metric": {
          "id": "subscribers",
          "name": "Illustrative subscribers",
          "sector": "general",
          "unit": "count",
          "definition": "Illustrative metric",
          "aliases": {},
          "favorable": "higher"
        },
        "unit": "count",
        "currency": null,
        "basis": "reported",
        "dimensions": {},
        "latest": {
          "id": "illustrative-fact-3",
          "symbol": "ILLUSTRATIVE",
          "metricId": "subscribers",
          "metric": {
            "id": "subscribers",
            "name": "Illustrative subscribers",
            "sector": "general",
            "unit": "count",
            "definition": "Illustrative metric",
            "aliases": {},
            "favorable": "higher"
          },
          "period": {
            "start": "2026-07-01",
            "end": "2026-09-30",
            "kind": "quarter",
            "fiscalYear": 2026,
            "fiscalQuarter": 3,
            "label": "Q3 2026"
          },
          "value": 300,
          "unit": "count",
          "currency": null,
          "basis": "reported",
          "dimensions": {},
          "confidence": 1,
          "seriesKey": "subscribers",
          "asOf": "2026-09-30T12:00:00.000Z",
          "supersedesId": null,
          "revision": 1,
          "current": true,
          "conflict": false,
          "evidence": [
            {
              "id": "illustrative-evidence-3",
              "documentId": "illustrative-document",
              "sourceId": "illustrative-filing",
              "sourceKind": "filing",
              "url": "https://example.invalid/illustrative-filing",
              "title": "ILLUSTRATIVE filing",
              "publishedAt": "2026-09-30T12:00:00.000Z",
              "country": "US",
              "language": "en",
              "quote": "ILLUSTRATIVE subscribers was 300.",
              "quoteOffset": 0,
              "quoteSourceLength": 100,
              "quoteMatchMode": "exact",
              "confidence": 1
            }
          ]
        },
        "observations": [
          {
            "id": "illustrative-fact-3",
            "symbol": "ILLUSTRATIVE",
            "metricId": "subscribers",
            "metric": {
              "id": "subscribers",
              "name": "Illustrative subscribers",
              "sector": "general",
              "unit": "count",
              "definition": "Illustrative metric",
              "aliases": {},
              "favorable": "higher"
            },
            "period": {
              "start": "2026-07-01",
              "end": "2026-09-30",
              "kind": "quarter",
              "fiscalYear": 2026,
              "fiscalQuarter": 3,
              "label": "Q3 2026"
            },
            "value": 300,
            "unit": "count",
            "currency": null,
            "basis": "reported",
            "dimensions": {},
            "confidence": 1,
            "seriesKey": "subscribers",
            "asOf": "2026-09-30T12:00:00.000Z",
            "supersedesId": null,
            "revision": 1,
            "current": true,
            "conflict": false,
            "evidence": [
              {
                "id": "illustrative-evidence-3",
                "documentId": "illustrative-document",
                "sourceId": "illustrative-filing",
                "sourceKind": "filing",
                "url": "https://example.invalid/illustrative-filing",
                "title": "ILLUSTRATIVE filing",
                "publishedAt": "2026-09-30T12:00:00.000Z",
                "country": "US",
                "language": "en",
                "quote": "ILLUSTRATIVE subscribers was 300.",
                "quoteOffset": 0,
                "quoteSourceLength": 100,
                "quoteMatchMode": "exact",
                "confidence": 1
              }
            ]
          }
        ]
      }
    ],
    "revisions": [],
    "dictionary": [],
    "access": "preview",
    "lockedRows": 0,
    "totalRows": 3,
    "truncated": false,
    "previewRows": 3,
    "methodology": "ILLUSTRATIVE company-disclosed operating metrics with source evidence."
  },
  "meta": {
    "dataset": "kpis-guidance",
    "asOf": null,
    "source": [
      {
        "id": "sec-edgar",
        "attribution": "U.S. Securities and Exchange Commission and the filing issuer",
        "licence": "Public SEC filings; preserve filing attribution and fair-access limits"
      }
    ],
    "historyStarts": null,
    "coverage": null,
    "lastUpdated": null,
    "sample": true,
    "note": "ILLUSTRATIVE: synthetic examples showing the response fields; not real company disclosures or published observations."
  }
}

Meta fields

Field: dataset
Here: The dataset id
In the example: "kpis-guidance"

Field: asOf
Here: The newest SEC filing behind the response
In the example: null

Field: source
Here: Attribution and licence of each source
In the example: 1 source

Field: historyStarts
Here: The first period in this response, not a dataset-wide start
In the example: null, not stated yet

Field: coverage
Here: Service-established coverage; null when unavailable.
In the example: null

Field: lastUpdated
Here: null: the store keeps publication dates, not read times
In the example: null

Field	Here	In the example
`dataset`	The dataset id	`"kpis-guidance"`
`asOf`	The newest SEC filing behind the response	null
`source`	Attribution and licence of each source	1 source
`historyStarts`	The first period in this response, not a dataset-wide start	null, not stated yet
`coverage`	Service-established coverage; null when unavailable.	null
`lastUpdated`	null: the store keeps publication dates, not read times	null

Sources

Source: U.S. Securities and Exchange Commission and the filing issuer
Licence: Public SEC filings; preserve filing attribution and fair-access limits

Source	Licence
U.S. Securities and Exchange Commission and the filing issuer	Public SEC filings; preserve filing attribution and fair-access limits

Errors

These routes can answer 400, 401, 402, 403, 404, 429, 503. See Errors for the codes.

Gloom Datasets reads stored data only: a call never starts a collection.