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
datakeep their form. In the sentences, dates stay ISO 8601 (2026-11-13) and amounts keep their digits. error.message,error.fixandnext[].reasonstay in English. A failed answer'ssummaryis 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
textof 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 forfed_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"}
valueis a JSON number, never a string.- Every number a source states carries
src, the id of an entry insources. A number Argus calculates has nosrcof its own; see Computed values. - A missing value is
nullwith anoteinstead ofsrc, for example"note": "not_reported". Argus never fills a gap with 0. restated: truehas 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 isstatus: revised, neverrestated. The filed financial facts say which of the two cases a read detects.valueandscaleare 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_historyreturnsdata.columnsanddata.bars, one row of plain values per bar, with onedata.srcfor the series and the currency and volume unit stated once. Anullin a row has no citable capture, or, in a split-adjusted row, is a volume before a split that thesplit_adjustednote explains; it is never data.intervalisday,weekormonth. Weekly and monthly rows are computed from the daily bars:data.computedistrueanddata.computed_fromsays which daily bars were used.data.adjustmentisrawor, when the call asks for it,split_adjusted: the rows are then computed from the raw bars and the split records,data.computedistrueanddata.computed_from.splitslists each split applied with its ownsrc.- Computed values. A number Argus computes from cited values is a plain
number next to them and a note says it is computed:
differenceandpercentinwhat_changed;changeandchange_percentinget_quote, whichdata.computedalso names, and itsrange_52w, whose high and low keep thesrcof the bar each comes from;cost_difference,cost_difference_percent,weight_percentandtotalsinget_portfolio. A computed value never has its ownsrcand is never a return, a rating or advice.get_financialsgives 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: truemarks it. It is never a filed figure and has nosrc.fromlists every cited value it rests on: the line item, the number, its unit, itsperiodordate, and thesrcof the filing or price that states it. A cited value keeps itsrestatedflag and itsnote.- A note in
notesnames the calculation:fourth_quarter_computed,computed_metrics,trailing_twelve_monthsormarket_cap_computed. - A margin or a growth rate has
unit: percentand no currency. - A value that cannot be calculated is
nullwith anotethat says why, like any missing value; it then has neithercomputednorfrom. - 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"}
idis a short label that is valid only inside one response.refis the stable evidence reference. Pass it toget_sourcesto 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,dateandurlare omitted when the source has none. Aurlis always a publichttpsorhttplink.- Filed financial values share one source per filing: every value a filing
reports cites the same entry, whose
refis 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_eventsstates the reporting person'snameandofficer_titleas that one filing gives them (ADR 0013). They are filer-written text under the event'ssrc: the answer adds the notesreported_personanduntrusted_text. - An
insider_filingsorownership_filingsevent ofwhats_newstates the form, its date and itssrc, and never a reporting person. The name stays on the filing's own event inget_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…"}
textis 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_textnote, and one with anytextsetsdata.text_trusttountrusted_source_text. - The excerpt appears in
textonly.summary,notes,sourcesandnextare 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 thenpartialand atext_unavailablenote says to open the link. - No other tool returns passages of source text. The reporting person's
nameandofficer_titleon 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 |
retryistrueonly fortemporarily_unavailableandquota_exceeded.- A
source_conflictmeans the sources disagree until one is revised. It istemporarily_unavailablewithretry: false. - An internal error that the same call would hit again is
internal_errorwithretry: falseand afixthat says not to repeat the call. Timeouts, lost connections and database or cache outages staytemporarily_unavailablewithretry: true. invalid_inputis used only when an argument is wrong. A read that fails on Argus's own data isinternal_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_exceededwith the message "Too many requests for this account are running at the same time." andretry_after_s: 2. not_coveredis about Argus's data, not about the market. Theargus://coverageresource 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_unavailablewithretry: true,retry_after_s: 20and 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 isquota_exceededwithretry_after_s: 3600. - A ticker is
not_foundonly 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 staysnot_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_inputmessage 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
truncatednote ("Showing N of M items in ..."), and puts the continuation call innextwhen the tool can continue. Sources cited only by removed items are dropped, and anokstatus becomespartial. - A response that cannot fit even after truncation is an
invalid_inputerror 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].textholds the same compact JSON._meta.argusholds{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.isErrorisfalsefor every envelope, includingunavailable,restrictedanderroranswers. It istrueonly when the tool itself failed, for example a tool that is not implemented yet.- Markdown renderings are not part of the MCP contract.