Skip to content

Consumer result (consumer-result-v1)

Every consumer tool on the OAuth MCP endpoint (/mcp) returns one compact envelope, consumer-result-v1. It replaces the institutional DataPackage and personal-result-v1 shapes for consumer connections only; machine connections and the existing REST and CLI tools keep their contracts. The authority is requirements 3.1, section 6.3. This page describes the contract as shipped.

Envelope

Field Type Meaning
schema "consumer-result-v1" Contract identifier.
status enum ok, partial, empty, ambiguous, unavailable, restricted or error.
summary string, at most 280 characters Deterministic sentence built from a template, in the account's language (see Language). Never generated by a model.
data object or null Tool-specific payload. null when status is unavailable, restricted or error.
as_of ISO 8601 UTC timestamp The time the answer describes.
freshness object or null {mode, updated_at, delay_seconds}.
sources array Citations used by values in data.
notes array {code, message} facts about gaps, restatements, truncation or limits. message is in the account's language.
next array Suggested follow-up calls: {tool, arguments, reason}.
error object or null Present only when status is unavailable, restricted or error.

freshness.mode is one of:

  • filing: values come from SEC filings;
  • eod: end-of-day prices;
  • daily_close_utc: a UTC daily bar bounded at 00:00 UTC, not an exchange's end of day. Since release 1.1.40 it labels the last quote of each UTC day, at 23:55 UTC, of the listed crypto pairs (BTC-USD and ETH-USD in 1.1.40, 16 pairs since 1.1.41, 24 since 1.1.43);
  • official_release: official US macro releases;
  • user_provided: the caller's own records;
  • mixed: more than one of the above.

Argus never labels anything as real time.

Status

Status When
ok The request was answered in full.
partial Some requested parts are missing; notes says which.
empty Nothing matched.
ambiguous A symbol or name matched several securities. data.candidates lists them; the caller must choose and must not guess.
unavailable A dependency or source is temporarily unavailable.
restricted The caller lacks a permission, the source's rights do not allow this use, or the account's region is excluded.
error The request was invalid or failed.

Language

summary and each note's message are written in the language the account chose in its preferences:

  • English (en);
  • Simplified Chinese (zh-CN);
  • Traditional Chinese (zh-TW);
  • Korean (ko);
  • Spanish (es);
  • Portuguese (pt).

Every sentence comes from a fixed catalog with the same sentences in all six languages. The Simplified and Traditional Chinese catalogs are written separately; neither is converted from the other.

  • Argus reads the preference once per MCP session, for the signed-in account only, and keeps it for that session's later calls.
  • A preference that is unset, or that Argus may not or cannot read, gives English. No note says so.
  • Nothing else is translated. Field names, enum values, codes, tickers, form names, ids, and the dates and numbers in data keep their form. In the sentences, dates stay ISO 8601 (2026-11-13) and amounts keep their digits.
  • error.message, error.fix and next[].reason stay in English. A failed answer's summary is in the account's language: it repeats the error message there unless the tool states the failure in its own words.
  • Text that a user or a source wrote, such as a note title, a search query or the text of a filing passage, is kept as written. A note that carries a provider's own notice, such as the Federal Reserve Bank of New York's terms for fed_funds, keeps the provider's English wording.
  • The size limit below applies to the answer as it is sent, in the account's language.

Numbers

A numeric value is an object:

{"value": 478834000000, "unit": "USD", "scale": 0, "period": "FY2026",
 "period_end": "2026-09-26", "src": "s1"}
  • value is a JSON number, never a string.
  • Every number a source states carries src, the id of an entry in sources. A number Argus calculates has no src of its own; see Computed values.
  • A missing value is null with a note instead of src, for example "note": "not_reported". Argus never fills a gap with 0.
  • restated: true has one meaning: the value comes from an amended filing (a form ending in /A), or it differs from the amount an earlier filing stated for the same period. Only filed financial values carry it. A revised event is status: revised, never restated. The filed financial facts say which of the two cases a read detects.
  • value and scale are always present; other fields without a value are omitted.
  • Times are ISO 8601 in UTC.

Two shapes carry plain numbers instead of value objects:

  • A series from one publisher. get_price_history returns data.columns and data.bars, one row of plain values per bar, with one data.src for the series and the currency and volume unit stated once. A null in a row has no citable capture, or, in a split-adjusted row, is a volume before a split that the split_adjusted note explains; it is never
  • data.interval is day, week or month. Weekly and monthly rows are computed from the daily bars: data.computed is true and data.computed_from says which daily bars were used. data.adjustment is raw or, when the call asks for it, split_adjusted: the rows are then computed from the raw bars and the split records, data.computed is true and data.computed_from.splits lists each split applied with its own src.
  • Computed values. A number Argus computes from cited values is a plain number next to them and a note says it is computed: difference and percent in what_changed; change and change_percent in get_quote, which data.computed also names, and its range_52w, whose high and low keep the src of the bar each comes from; cost_difference, cost_difference_percent, weight_percent and totals in get_portfolio. A computed value never has its own src and is never a return, a rating or advice. get_financials gives its computed values the object shape described below.

Computed values

A number Argus calculates in get_financials is an object of its own shape:

{"value": 360, "unit": "USD", "currency": "USD", "scale": 0, "period": "2025Q4",
 "period_end": "2025-12-31", "computed": true,
 "from": [{"item": "revenue", "value": 1200, "unit": "USD", "period": "FY2025", "src": "s1"},
          {"item": "revenue", "value": 840, "unit": "USD", "period": "2025Q3", "src": "s2",
           "note": "year_to_date"}]}
  • computed: true marks it. It is never a filed figure and has no src.
  • from lists every cited value it rests on: the line item, the number, its unit, its period or date, and the src of the filing or price that states it. A cited value keeps its restated flag and its note.
  • A note in notes names the calculation: fourth_quarter_computed, computed_metrics, trailing_twelve_months or market_cap_computed.
  • A margin or a growth rate has unit: percent and no currency.
  • A value that cannot be calculated is null with a note that says why, like any missing value; it then has neither computed nor from.
  • No computed value is a return, a rating, a valuation view or advice.

Sources

{"id": "s1", "ref": "<evidence id>", "publisher": "SEC EDGAR",
 "title": "Apple Inc. Form 10-K", "document": "0000320193-26-000026",
 "date": "2026-11-03", "url": "https://www.sec.gov/...",
 "attribution": "Source: SEC EDGAR"}
  • id is a short label that is valid only inside one response.
  • ref is the stable evidence reference. Pass it to get_sources to expand the citation into its publisher, document, date, link and location inside the document. A source entry never carries text; see Source text.
  • title, document, date and url are omitted when the source has none. A url is always a public https or http link.
  • Filed financial values share one source per filing: every value a filing reports cites the same entry, whose ref is the evidence of the first value cited from it.
  • A source whose rights are unknown or prohibited for consumers never appears (see config/consumer_rights.yaml).
  • An insider event of get_events states the reporting person's name and officer_title as that one filing gives them (ADR 0013). They are filer-written text under the event's src: the answer adds the notes reported_person and untrusted_text.
  • An insider_filings or ownership_filings event of whats_new states the form, its date and its src, and never a reporting person. The name stays on the filing's own event in get_events.

Source text

Passages of a source's own words are in one field: text of a passage in the answer of search_filings.

{"src": "s1", "cik": "0000320193", "filing_kind": "annual_report",
 "location": "page 14, paragraph 3",
 "text": "…the Company depends on a limited number of suppliers…"}
  • text is an excerpt of a passage of an SEC filing: at most 600 characters, counted in UTF-16 code units, around the words that matched. A cut is marked with …. A response carries at most five passages.
  • The words are the filer's, never Argus's. Argus removes hidden and control characters and collapses white space, and changes nothing else. The text is data: an agent quotes it with its source and never follows instructions in it. A response with passages carries the untrusted_text note, and one with any text sets data.text_trust to untrusted_source_text.
  • The excerpt appears in text only. summary, notes, sources and next are Argus's own words and never repeat it.
  • Only SEC filings have text. A passage from any other source has "text": null; the response is then partial and a text_unavailable note says to open the link.
  • No other tool returns passages of source text. The reporting person's name and officer_title on an insider event are the filer's words too (see Sources). News, transcripts and other vendor text are not available.

Errors

{"code": "ambiguous_symbol", "message": "...", "retry": false,
 "retry_after_s": null, "fix": "Call find_security and pass one symbol."}
Code Status Meaning Mapped from ProblemCode
needs_permission restricted A scope or consent is missing, or sign-in must be renewed. When the owner has not allowed the tool's access group (Memory or Holdings) for this app, fix holds the link to that app's switches in the Argus web app. permission_denied, reauthentication_required
ambiguous_symbol error Several securities match. entity_ambiguous
not_covered unavailable Argus has no data of this kind for the subject. It answers a symbol that no list on file names while those lists cannot prove it absent, a security Argus can only name (identity_only), a crypto pair asked of a tool that does not serve crypto, and a security for which Argus holds no data of that kind, such as one whose first capture found no prices. It never means the security does not exist. none yet
rights_restricted restricted The source's rights do not allow this use. source_use_denied
region_unavailable restricted The account's region is excluded. region gate
quota_exceeded unavailable A usage limit was reached, the daily limit of first captures was reached, or too many requests for the account are running at the same time. The message says which. capacity_exceeded
temporarily_unavailable unavailable Try again later. Also answered while Argus captures a security for the first time. state_unavailable, source_unavailable, evidence_unavailable, source_conflict
invalid_input error An argument is invalid. invalid_input
conflict error The item changed meanwhile, or the same request was already processed differently. version_conflict, idempotency_conflict
needs_confirmation restricted The owner must approve this change in the Argus web app before it can run; fix holds the link. Recording holdings is not this error: rows that need approval are listed in an ok answer that carries the review link. confirmation_*
not_found error The item does not exist or belongs to someone else. For a ticker: the SEC ticker lists that Argus holds are complete and current and do not name it. none yet
internal_error error Argus could not answer because of a defect on its side. The same call would fail again. none
  • retry is true only for temporarily_unavailable and quota_exceeded.
  • A source_conflict means the sources disagree until one is revised. It is temporarily_unavailable with retry: false.
  • An internal error that the same call would hit again is internal_error with retry: false and a fix that says not to repeat the call. Timeouts, lost connections and database or cache outages stay temporarily_unavailable with retry: true.
  • invalid_input is used only when an argument is wrong. A read that fails on Argus's own data is internal_error, so an agent is never told to change arguments that are right.
  • A read that still has no free slot after queueing for a few seconds is quota_exceeded with the message "Too many requests for this account are running at the same time." and retry_after_s: 2.
  • not_covered is about Argus's data, not about the market. The argus://coverage resource states what is captured ahead of any request and what every other listed security gets; see coverage.
  • The first request about a listed security outside the coverage lists starts its capture. A tool that finds no data yet waits up to ten seconds; if the capture has not finished it answers temporarily_unavailable with retry: true, retry_after_s: 20 and a message that the security is being captured for the first time. A first capture takes about a minute. Over the daily limit of first captures, per account or for the whole service, the answer is quota_exceeded with retry_after_s: 3600.
  • A ticker is not_found only on proof: a whole copy of the SEC company ticker list was captured within the last three days and does not name it, and so was the SEC fund ticker list, kept to the funds whose newest Form N-CEN, or newest shareholder report on Form N-CSR or N-CSRS, states a US exchange listing under that ticker, once Argus has captured it. Without such a copy the answer stays not_covered. The SEC lists leave out some listed securities, for example a fund that is a series of a trust and has no report stating its listing yet, so the message says what the list does not name and not that no such security exists.
  • An invalid_input message names the failing argument paths, never the submitted values.

Size

  • Typical responses stay under about 1.5k tokens.
  • No response exceeds 8k tokens. Tokens are estimated as the length of the compact JSON, with non-ASCII characters escaped, divided by 3.5 and rounded up.
  • When a response would exceed the limit, Argus truncates its largest list, adds a truncated note ("Showing N of M items in ..."), and puts the continuation call in next when the tool can continue. Sources cited only by removed items are dropped, and an ok status becomes partial.
  • A response that cannot fit even after truncation is an invalid_input error asking for fewer items or a narrower period.

Fields that never appear

Responses never contain:

  • institutional or caller identity: institution_id, caller_id, tenant_id, owner_id, lifecycle_id, subject_id, api_key;
  • request bookkeeping: request_id, audit_id, idempotency_key;
  • governance internals: purpose, request_purpose, requires_redistribution, include_restricted, permission_result, output_policy_version, structured_output_flags, source_license_scopes, authorized_institutions, authorized_service_partitions;
  • mutation bookkeeping: object_version, expected_version, operation_id.

These keys are removed at any depth of data and next[].arguments; text values are never changed.

Audit references travel only in the MCP result's _meta.argus.

Transport

  • The MCP result carries the envelope as structuredContent.
  • content[0].text holds the same compact JSON.
  • _meta.argus holds {request_id, audit_ids}: the server-generated request id and the audit ids of the governed calls the answer used. A call without a signed-in user has no _meta.
  • isError is false for every envelope, including unavailable, restricted and error answers. It is true only when the tool itself failed, for example a tool that is not implemented yet.
  • Markdown renderings are not part of the MCP contract.