Skip to main content
Glama

Secedgar Get Snapshot

secedgar_get_snapshot
Read-onlyIdempotent

Build a company financial profile in one call: the latest value of every supported XBRL concept, grouped by statement. Reads the filer's complete companyfacts payload once rather than one request per concept, so it replaces a run of secedgar_get_financials calls when the question is "what do this company's financials look like right now". Values use the same frame dedup and tag priority as secedgar_get_financials, so the two agree for any concept they both cover. Duration concepts (income statement, cash flow, per-share) report their latest full year and latest single quarter; balance-sheet and entity-info concepts report their latest point-in-time value, since that is the only form they are filed in. A concept the filer does not report is listed under gaps with the XBRL tags that were tried — never zero-filled or interpolated. Use secedgar_get_financials for a full time series of one concept, and secedgar_compare_companies to put several companies side by side.

Input Schema

NameRequiredDescriptionDefault
companyYesTicker symbol (e.g. "AAPL") or CIK number. Ticker is preferred.
taxonomyNoXBRL taxonomy to resolve concepts under. Every concept is looked up in this one taxonomy, so ifrs-full covers only the concepts with confirmed IFRS tag variants and the rest — including the dei entity-info concepts — come back under gaps. Leave at us-gaap for domestic filers, where each concept uses its own preferred taxonomy.us-gaap
period_typeNoWhich duration periods to report per concept: the latest full year, the latest single quarter, or both (default). Balance-sheet and entity-info concepts are point-in-time and always report their latest instant value regardless of this setting.both

Output Schema

NameRequiredDescriptionDefault
cikNoResolved CIK, zero-padded to 10 digits.
gapsNoConcepts with no value for this filer, never zero-filled or interpolated.
errorNoPresent when the call failed. Absent on success.
linesNoResolved concepts, ordered by statement group then concept name.
caveatsNoCompleteness warnings, else empty: quarters missing from every recent year (SEC reports fiscal Q4 only within the 10-K), and, prefixed with the concept name, lines stopping 2+ years behind the filer's newest period.
companyNoResolved entity name (SEC-conformed).
taxonomyNoTaxonomy the concepts were resolved under, echoed from input.
period_typeNoDuration periods reported, echoed from input.
concepts_totalNoConcepts in the supported catalog that were attempted.
concepts_resolvedNoConcepts that produced at least one value.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a CIK. `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous. `no_company_facts`: The filer has no XBRL facts at all — pre-XBRL, foreign private issuer, or a non-operating registrant. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: The last of three attempts to reach SEC EDGAR got no HTTP response — the connection failed, or no response headers arrived within 15 seconds. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a CIK. `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous. `no_company_facts`: The filer has no XBRL facts at all — pre-XBRL, foreign private issuer, or a non-operating registrant. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
  2. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a CIK. `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous. `no_company_facts`: The filer has no XBRL facts at all — pre-XBRL, foreign private issuer, or a non-operating registrant. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a CIK. `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous. `no_company_facts`: The filer has no XBRL facts at all — pre-XBRL, foreign private issuer, or a non-operating registrant. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: The last of three attempts to reach SEC EDGAR got no HTTP response — the connection failed, or no response headers arrived within 15 seconds. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "company_not_found",
      -  "ambiguous_company",
      -  "no_company_facts",
      -  "rate_limited"
      -]New value: +[
      +  "company_not_found",
      +  "ambiguous_company",
      +  "no_company_facts",
      +  "rate_limited",
      +  "sec_unreachable"
      +]
  3. Changed15 schema fields changed
    • changedOutput schema / properties / caveats / description
      Previous value: -"Data-completeness warnings. One entry when one or two calendar quarters are absent from every recent qualifying year, because SEC reports a filer's fiscal Q4 as the 10-K residual rather than a discrete quarterly fact — this applies to calendar-year filers (no discrete Q4) as much as to off-calendar ones, and a filer whose other fiscal quarters span non-calendar durations loses a second quarter the same way. One further entry, prefixed with the concept name, per line whose values stop at least two full years behind the newest period this filer reports anywhere in the profile — either because the line resolved to an XBRL tag SEC has retired from the taxonomy, or because a current tag's series simply ends, which is what a migration to a different element or a dropped disclosure looks like. Empty when nothing needs flagging."New value: +"Completeness warnings, else empty: quarters missing from every recent year (SEC reports fiscal Q4 only within the 10-K), and, prefixed with the concept name, lines stopping 2+ years behind the filer's newest period."
    • changedOutput schema / properties / gaps / description
      Previous value: -"Concepts with no value for this filer. Deliberately explicit — a missing concept is never zero-filled or interpolated."New value: +"Concepts with no value for this filer, never zero-filled or interpolated."
    • changedOutput schema / properties / gaps / items / description
      Previous value: -"One concept the filer does not report, with the tags that were tried."New value: +"One concept the filer does not report."
    • changedOutput schema / properties / lines / items / description
      Previous value: -"One resolved concept with its latest value per period kind."New value: +"One concept with its latest values: duration concepts carry annual and quarterly as period_type allows; point-in-time concepts carry instant only."
    • changedOutput schema / properties / lines / items / properties / annual / description
      Previous value: -"Latest full-year (CY####) value. Absent for point-in-time concepts and when period_type excludes it."New value: +"Latest full-year (CY####) value."
    • changedOutput schema / properties / lines / items / properties / annual / properties / accession_number / description
      Previous value: -"Source filing accession number — pass to secedgar_get_filing."New value: +"Source filing accession number for secedgar_get_filing."
    • changedOutput schema / properties / lines / items / properties / annual / properties / tag / description
      Previous value: -"XBRL tag this value was reported under — differs from the line's tag when an older or successor tag in the concept answers this period."New value: +"XBRL tag behind this value; can differ from the line's tag."
    • changedOutput schema / properties / lines / items / properties / instant / description
      Previous value: -"Latest point-in-time (CY####Q#I) value. Present for balance-sheet and entity-info concepts."New value: +"Latest point-in-time (CY####Q#I) value."
    • changedOutput schema / properties / lines / items / properties / instant / properties / accession_number / description
      Previous value: -"Source filing accession number — pass to secedgar_get_filing."New value: +"Source filing accession number for secedgar_get_filing."
    • changedOutput schema / properties / lines / items / properties / instant / properties / tag / description
      Previous value: -"XBRL tag this value was reported under — differs from the line's tag when an older or successor tag in the concept answers this period."New value: +"XBRL tag behind this value; can differ from the line's tag."
    • changedOutput schema / properties / lines / items / properties / quarterly / description
      Previous value: -"Latest single-quarter (CY####Q#) value. Absent for point-in-time concepts and when period_type excludes it."New value: +"Latest single-quarter (CY####Q#) value."
    • changedOutput schema / properties / lines / items / properties / quarterly / properties / accession_number / description
      Previous value: -"Source filing accession number — pass to secedgar_get_filing."New value: +"Source filing accession number for secedgar_get_filing."
    • changedOutput schema / properties / lines / items / properties / quarterly / properties / tag / description
      Previous value: -"XBRL tag this value was reported under — differs from the line's tag when an older or successor tag in the concept answers this period."New value: +"XBRL tag behind this value; can differ from the line's tag."
    • changedOutput schema / properties / lines / items / properties / tag / description
      Previous value: -"XBRL tag behind the newest value — each point names its own when the concept walks several."New value: +"XBRL tag behind the newest value; each point names its own."
    • changedOutput schema / properties / lines / items / properties / unit / description
      Previous value: -"Unit of measure of the newest value (e.g. \"USD\", \"USD/shares\", \"shares\")."New value: +"Unit of every point on the line (e.g., \"USD\"). A concept in several units reads its newest value's unit, then the one with more periods; secedgar_get_financials reads the others."
  4. Changed8 schema fields changed
    • addedOutput schema / properties / lines / items / properties / annual / properties / tag
      Added value: +{
      +  "description": "XBRL tag this value was reported under — differs from the line's tag when an older or successor tag in the concept answers this period.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / lines / items / properties / annual / required
      Previous value: -[
      -  "period",
      -  "value",
      -  "period_end",
      -  "form",
      -  "accession_number"
      -]New value: +[
      +  "period",
      +  "value",
      +  "period_end",
      +  "form",
      +  "accession_number",
      +  "tag"
      +]
    • addedOutput schema / properties / lines / items / properties / instant / properties / tag
      Added value: +{
      +  "description": "XBRL tag this value was reported under — differs from the line's tag when an older or successor tag in the concept answers this period.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / lines / items / properties / instant / required
      Previous value: -[
      -  "period",
      -  "value",
      -  "period_end",
      -  "form",
      -  "accession_number"
      -]New value: +[
      +  "period",
      +  "value",
      +  "period_end",
      +  "form",
      +  "accession_number",
      +  "tag"
      +]
    • addedOutput schema / properties / lines / items / properties / quarterly / properties / tag
      Added value: +{
      +  "description": "XBRL tag this value was reported under — differs from the line's tag when an older or successor tag in the concept answers this period.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / lines / items / properties / quarterly / required
      Previous value: -[
      -  "period",
      -  "value",
      -  "period_end",
      -  "form",
      -  "accession_number"
      -]New value: +[
      +  "period",
      +  "value",
      +  "period_end",
      +  "form",
      +  "accession_number",
      +  "tag"
      +]
    • changedOutput schema / properties / lines / items / properties / tag / description
      Previous value: -"XBRL tag that produced the value."New value: +"XBRL tag behind the newest value — each point names its own when the concept walks several."
    • changedOutput schema / properties / lines / items / properties / unit / description
      Previous value: -"Unit of measure (e.g. \"USD\", \"USD/shares\", \"shares\")."New value: +"Unit of measure of the newest value (e.g. \"USD\", \"USD/shares\", \"shares\")."
  5. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a CIK `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous `no_company_facts`: The filer has no XBRL facts at all — pre-XBRL, foreign private issuer, or a non-operating registrant Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a CIK. `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous. `no_company_facts`: The filer has no XBRL facts at all — pre-XBRL, foreign private issuer, or a non-operating registrant. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "company_not_found",
      -  "ambiguous_company",
      -  "no_company_facts"
      -]New value: +[
      +  "company_not_found",
      +  "ambiguous_company",
      +  "no_company_facts",
      +  "rate_limited"
      +]
  6. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "company",
      +      "cik",
      +      "taxonomy",
      +      "period_type",
      +      "concepts_resolved",
      +      "concepts_total",
      +      "lines",
      +      "gaps",
      +      "caveats"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a CIK `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous `no_company_facts`: The filer has no XBRL facts at all — pre-XBRL, foreign private issuer, or a non-operating registrant Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "company_not_found",
      +            "ambiguous_company",
      +            "no_company_facts"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "company",
      -  "cik",
      -  "taxonomy",
      -  "period_type",
      -  "concepts_resolved",
      -  "concepts_total",
      -  "lines",
      -  "gaps",
      -  "caveats"
      -]
  7. Changed1 schema field changed
    • changedOutput schema / properties / caveats / description
      Previous value: -"Data-completeness warnings. One entry when one or two calendar quarters are absent from every recent qualifying year, because SEC reports a filer's fiscal Q4 as the 10-K residual rather than a discrete quarterly fact — this applies to calendar-year filers (no discrete Q4) as much as to off-calendar ones, and a filer whose other fiscal quarters span non-calendar durations loses a second quarter the same way. One further entry per line that resolved to an XBRL tag SEC has retired from the taxonomy, whose values may stop years short of the filer's latest report. Empty when nothing needs flagging."New value: +"Data-completeness warnings. One entry when one or two calendar quarters are absent from every recent qualifying year, because SEC reports a filer's fiscal Q4 as the 10-K residual rather than a discrete quarterly fact — this applies to calendar-year filers (no discrete Q4) as much as to off-calendar ones, and a filer whose other fiscal quarters span non-calendar durations loses a second quarter the same way. One further entry, prefixed with the concept name, per line whose values stop at least two full years behind the newest period this filer reports anywhere in the profile — either because the line resolved to an XBRL tag SEC has retired from the taxonomy, or because a current tag's series simply ends, which is what a migration to a different element or a dropped disclosure looks like. Empty when nothing needs flagging."
  8. Changed1 schema field changed
    • changedOutput schema / properties / caveats / description
      Previous value: -"Data-completeness warnings about the quarterly values. Populated when one calendar quarter is absent from every recent fully-reported year, because SEC reports a filer's fiscal Q4 as the 10-K residual rather than a discrete quarterly fact — this applies to calendar-year filers (no discrete Q4) as much as to off-calendar ones. Empty when nothing needs flagging."New value: +"Data-completeness warnings. One entry when one or two calendar quarters are absent from every recent qualifying year, because SEC reports a filer's fiscal Q4 as the 10-K residual rather than a discrete quarterly fact — this applies to calendar-year filers (no discrete Q4) as much as to off-calendar ones, and a filer whose other fiscal quarters span non-calendar durations loses a second quarter the same way. One further entry per line that resolved to an XBRL tag SEC has retired from the taxonomy, whose values may stop years short of the filer's latest report. Empty when nothing needs flagging."
  9. Added

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnly/idempotent/openWorld), but the description adds substantial semantics beyond that: single companyfacts fetch vs per-concept requests, frame dedup and tag priority shared with get_financials so outputs agree, duration concepts returning latest FY and latest quarter while balance-sheet/entity-info return point-in-time, and gaps listed with attempted tags rather than zero-filled.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and the alternative routing, and every sentence carries information (dedup semantics, period form rules, gap handling). It is dense and long, with a few clauses that could be tightened, but nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values needn't be explained, yet the description still covers profile shape (grouped by statement), period form per concept class, and gap reporting. That is complete for an agent to call and interpret this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so company, taxonomy, and period_type are fully documented in the schema already. The description reinforces the period/taxonomy behavior but adds little syntax or format detail beyond what the schema states; baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Build a company financial profile in one call: the latest value of every supported XBRL concept, grouped by statement') and explicitly distinguishes itself from secedgar_get_financials and secedgar_compare_companies, so the agent can pick it without inspecting schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the exact condition that selects this tool ('what do this company's financials look like right now') and both alternatives with their trade-offs: get_financials for a full time series of one concept, compare_companies for side-by-side. Explicit when-to-use and when-to-use-otherwise.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.