Meta

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/gloom-sh/json-schema/gloom-sh-meta-schema.json",
  "title": "Meta",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gloom-sh-openapi.json#/components/schemas/Meta",
  "type": "object",
  "required": [
    "dataset",
    "requestId",
    "asOf",
    "dataThrough",
    "historyStart",
    "updatedAt",
    "page",
    "next",
    "coverage",
    "source",
    "notices",
    "symbols"
  ],
  "properties": {
    "dataset": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "gpu",
        "hiring-jobs",
        "hiring-momentum",
        "app-attention",
        "awards",
        "kpis-guidance",
        "credit-documents",
        "power",
        "perps",
        "catalysts",
        "supply-chain",
        "exposure",
        "transcripts",
        "exec-pay",
        "risk-factors",
        "events",
        "document-search",
        "news",
        "social-mentions",
        "cpi",
        "energy-inventories",
        "cot",
        "short-volume",
        "short-interest",
        "sec",
        "congress",
        "macro",
        "central-bank-rates",
        "cds",
        "debt-maturities",
        "revenue-breakdown",
        "depositary-receipts",
        "bond-trades",
        "market-data",
        "futures",
        "rate-path",
        "options",
        "earnings",
        "ipo",
        "mna",
        "equity-screener",
        "crypto",
        "session-tape",
        "analyst-estimates",
        null
      ]
    },
    "requestId": {
      "type": "string",
      "description": "Quote it to support."
    },
    "asOf": {
      "type": [
        "string",
        "null"
      ],
      "description": "The point in time you asked for with asOf, or null for the latest."
    },
    "dataThrough": {
      "type": [
        "string",
        "null"
      ],
      "description": "The newest date or time the data covers."
    },
    "historyStart": {
      "type": [
        "string",
        "null"
      ],
      "description": "Earliest date the dataset has history for, when known; otherwise null."
    },
    "updatedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the data last changed, when known."
    },
    "page": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "required": [
            "limit",
            "hasMore",
            "nextCursor",
            "total"
          ],
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1
            },
            "hasMore": {
              "type": "boolean"
            },
            "nextCursor": {
              "type": [
                "string",
                "null"
              ]
            },
            "total": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0,
              "description": "Rows that match the query on every page, where the route counts them; null where it does not."
            }
          }
        }
      ],
      "description": "Paging of a list; null for a single record."
    },
    "next": {
      "type": [
        "string",
        "null"
      ],
      "description": "The next page as a ready URL, or null."
    },
    "coverage": {
      "description": "Service-established coverage; null when unavailable."
    },
    "source": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "attribution",
          "licence"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "attribution": {
            "type": "string"
          },
          "licence": {
            "type": "string"
          }
        }
      }
    },
    "delayed": {
      "type": "boolean",
      "const": true,
      "description": "Present, and true, only on market prices that follow delayed-data access."
    },
    "notices": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Notice"
      },
      "description": "Caveats that change how to read the data: disclaimers, gaps, illustrative samples."
    },
    "sampledAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "Only on sample routes: when the sample was read from the dataset. Null for the built-in example, served until the first daily read succeeds."
    },
    "symbols": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SymbolResult"
          }
        }
      ],
      "description": "Each listing a symbols= call named, in the order sent: as sent, its canonical listing and whether it was read. Only ok listings are charged. Null when the call named none."
    },
    "cursor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Only on a change feed (/v1/catalysts/changes, /v1/insider-trades/changes): the cursor to send as cursor on the next poll, with the same since and symbols. It is there caught up too, when meta.next is null. One cursor serves all the symbols of the call: on /v1/catalysts/changes it is the earliest of the listings', each of which is also in meta.symbols."
    },
    "checkedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "Only on a change feed (/v1/catalysts/changes, /v1/insider-trades/changes): when its collector last finished reading its sources, rows or none, so a quiet feed reads apart from a stalled one; on /v1/catalysts/changes the newest of its sources' last reads. It is in no ETag, and the X-Checked-At header carries it on a 304 too. Null when not recorded."
    },
    "pointInTime": {
      "type": "object",
      "required": [
        "cutoff",
        "basis",
        "versions"
      ],
      "properties": {
        "cutoff": {
          "type": "string",
          "format": "date-time",
          "description": "The last moment the read counts, in UTC: a date's is the end of that day."
        },
        "basis": {
          "type": "string",
          "enum": [
            "observedAt",
            "publishedAt"
          ],
          "description": "observedAt: the rows Gloom had stored by the cutoff. publishedAt: the route does not record when Gloom stored each row, so the rows are those their source had published by then."
        },
        "versions": {
          "type": "string",
          "enum": [
            "kept",
            "unchanged",
            "latest"
          ],
          "description": "kept: each row has the values it had then. unchanged: so does each row, and a row changed since is left out. latest: each row has its values now, which may hold a revision made after the cutoff."
        }
      },
      "description": "Only on a call that sent asOf: what the answer is. Unless basis is observedAt and versions kept, a point_in_time notice says what the route cannot give."
    }
  },
  "$defs": {
    "Notice": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "SymbolResult": {
      "type": "object",
      "required": [
        "input",
        "symbol",
        "status"
      ],
      "properties": {
        "input": {
          "type": "string",
          "description": "As sent."
        },
        "symbol": {
          "type": [
            "string",
            "null"
          ],
          "description": "The canonical listing: the bare symbol on a US venue (BRK.B), else SYMBOL:MIC (AIR:XPAR). Null when the notation names no listing."
        },
        "status": {
          "type": "string",
          "enum": [
            "ok",
            "empty",
            "not_found",
            "unavailable",
            "partial"
          ],
          "description": "ok: read and charged. empty: a listing Gloom knows that the dataset holds nothing for here, or does not cover (an outside_coverage notice names those); free. not_found: no listing Gloom knows; free. unavailable: it could not be read now; free, retry later. partial: read in part, free, send it again."
        },
        "cursor": {
          "type": [
            "string",
            "null"
          ],
          "description": "Only on a route that pages by its own cursor: where this listing reads on. Send it as cursor with symbols= naming this listing alone. On a change feed it is there caught up too. Null when the listing has no more, or was not read."
        }
      }
    }
  }
}