BatchResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/filings-tools/json-schema/filings-tools-batch-result-schema.json",
  "title": "BatchResult",
  "x-generated": "2026-11-07",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/filings-tools-openapi.json#/components/schemas/BatchResult",
  "type": "object",
  "required": [
    "form",
    "section",
    "count",
    "calls",
    "duplicates",
    "items"
  ],
  "properties": {
    "form": {
      "type": "string"
    },
    "section": {
      "type": "string"
    },
    "count": {
      "type": "integer",
      "description": "Companies in the answer, after duplicates are removed."
    },
    "calls": {
      "type": "integer",
      "description": "Calls this request used: one per company, less those with status `error`, at least one. It assumes the give-back for `error` companies went through; an `X-RateLimit-Refund: failed` header means the give-back was not confirmed and those calls may still count."
    },
    "duplicates": {
      "type": "array",
      "description": "Tickers that named a company already in the batch, such as a CIK sent with its ticker. Answered and charged once.",
      "items": {
        "type": "object",
        "required": [
          "ticker",
          "sameAs"
        ],
        "properties": {
          "ticker": {
            "type": "string"
          },
          "sameAs": {
            "type": "string"
          }
        }
      }
    },
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/BatchItem"
      },
      "description": "One per company, in the order of `tickers`."
    }
  },
  "$defs": {
    "BatchItem": {
      "type": "object",
      "description": "One company of a batch call. `status` says what was found; `filing` and `section` are present when they were.",
      "required": [
        "ticker",
        "status"
      ],
      "properties": {
        "ticker": {
          "type": "string",
          "description": "As sent, upper-cased."
        },
        "status": {
          "type": "string",
          "enum": [
            "ok",
            "unknown_ticker",
            "no_filing",
            "no_section",
            "error"
          ],
          "description": "`ok`: the section is here. `unknown_ticker`: not in the SEC ticker list. `no_filing`: no filing of this form in the recent EDGAR window. `no_section`: the parser found no such section in the latest filing. `error`: the filing could not be read this time, and that company is not charged."
        },
        "company": {
          "type": "object",
          "required": [
            "cik",
            "ticker",
            "name"
          ],
          "properties": {
            "cik": {
              "type": "integer"
            },
            "ticker": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          }
        },
        "filing": {
          "type": "object",
          "required": [
            "id",
            "form",
            "period",
            "filed",
            "url",
            "source",
            "sectionsUrl"
          ],
          "properties": {
            "id": {
              "type": "string",
              "pattern": "^[0-9]+-[0-9]{18}$",
              "description": "Use it in the per-filing routes."
            },
            "form": {
              "type": "string"
            },
            "period": {
              "type": "string",
              "description": "The period of the report, or the filing date when there is none."
            },
            "filed": {
              "type": "string",
              "format": "date"
            },
            "url": {
              "type": "string",
              "format": "uri",
              "description": "The reader page on filings.tools."
            },
            "source": {
              "type": "string",
              "format": "uri",
              "description": "The primary document on sec.gov."
            },
            "sectionsUrl": {
              "type": "string",
              "format": "uri",
              "description": "The per-filing sections route for this section: the whole text when `section.truncated` is true."
            }
          }
        },
        "section": {
          "type": "object",
          "required": [
            "id",
            "title",
            "markdown",
            "chars",
            "truncated"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "markdown": {
              "type": "string"
            },
            "chars": {
              "type": "integer",
              "description": "Length of the whole section, in characters."
            },
            "truncated": {
              "type": "boolean",
              "description": "The text was cut to fit the answer's size limit."
            },
            "returned_characters": {
              "type": "integer",
              "description": "With `truncated`: the characters returned."
            }
          }
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "section",
              "code",
              "message"
            ],
            "properties": {
              "section": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        },
        "availableSections": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "With `no_section`: the section ids the filing does have."
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}