Fetch & traces

A fetch is FACE’s main pipeline. It reads the selected data sources on a runner, profiles and reconciles them, runs the posture, rules, hypothesis and twin agents on the sovereign model plane, and returns one analysis with decisions, action cards and their judgements. FetchService starts fetches, streams their progress, lists past runs, and generates procedures.

Fetches always execute on a runner, never on the control plane. The control plane checks the tenant’s compute budget, then hands the work to an enrolled runner or dials the managed runner (see Configuration, connections & runners). Each successful fetch charges 25 compute units (see Metering & schedules).

Summary

Service	RPC	Kind	Purpose
FetchService	RunFetch	Unary	Run a fetch and return the analysis
FetchService	RunFetchStream	Server streaming	Run a fetch, streaming phase progress
FetchService	ListTraces	Unary	List recent fetch runs
FetchService	GetTraceDetails	Unary	One run’s command, analysis and SQL
FetchService	GenerateSOP	Unary	Draft a standard operating procedure
FetchService	Talk	Bidirectional streaming	Not implemented
FetchService	ListFetchStarters	Unary	Suggested fetch prompts

FetchService/GetDispatchKey is internal to the platform (served only by a runner, and only to a verified mesh peer) and is not documented here.

FetchService

Full name semantics.v1.FetchService.

RunFetch

rpc RunFetch(RunFetchRequest) returns (RunFetchResponse);

Kind: Unary. A fetch can take many minutes: set a generous deadline, or use RunFetchStream.
Auth: Bearer session.
Errors: None beyond authentication. Every outcome is in the response. Check success and message:

Situation	Response
Compute budget exhausted	`success: false`, `message` asks you to top up compute units. Nothing ran.
No runner available or reachable	`success: false`, `message` says so. The fetch never runs on the control plane.
No selected source could be read	`success: false`, `message` names each source and why.
Some analysis phases failed	`success: false`, `message` gives the verdict, and `analysis` carries what was produced.
Complete	`success: true`, `transaction_id` and `analysis` set.

Read analysis.source_notices even on success: it reports sources that could not be read and where SQL actually ran.

Request: RunFetchRequest

Shared by RunFetch and RunFetchStream.

Field	Type	Description
`command`	`string`	What to analyse, in plain language, for example `Which shipments are running late, and why?`.
`documents`	`repeated string`	Attached documents, such as regulatory rules.
`connection_id`	`string`	The primary data source.
`runner_id`	`string`	The runner to use. The compute budget is always the tenant’s, whatever runner is named.
`enrichment_connection_ids`	`repeated string`	Additional sources to read.
`trigger_type`	`RunFetchRequest.TriggerType`	What started the run.
`schedule_config`	`string`	Optional cron expression or description.
`job_id`	`string`	Your job id. Used as the charge reference when there is no transaction id.
`language_preference`	`string`	Preferred language for the analysis.
`notify_via_call`	`bool`	After the run, phone the carrier number in the integration config with the spoken summary. Nothing happens if no number is configured.
`notify_via_whatsapp`	`bool`	After the run, send the spoken summary to the WhatsApp number in the integration config. Nothing happens if no number is configured.
`session_eda`	`bool`	Run only the fast first phase (data domains, maturity, rules reconciliation, knowledge graph) and skip the deep hypothesis and twin agents.
`synapse_threshold`	`double`	Minimum absolute Pearson r for the pass to record a measured link (“synapse”) between two data domains. 0 means the default, 0.5. Higher values give fewer, stronger links.
`dispatched_connections`	`repeated Connection`	Internal. Set by the platform when it forwards work to a runner. A client value is overwritten or ignored.
`dispatch_id`	`string`	Internal. As above.
`dispatched_credentials`	`repeated SealedCredential`	Internal. As above. Clients never see or send credentials here.

Response: RunFetchResponse

Field	Type	Description
`success`	`bool`	`true` only for a complete run.
`message`	`string`	Why, when `success` is `false`.
`transaction_id`	`string`	The run’s id, also used as the trace id.
`analysis`	`FetchAnalysisResult`	The analysis. Also present on a partial run.

RunFetchStream

rpc RunFetchStream(RunFetchRequest) returns (stream RunFetchUpdate);

Kind: Server streaming. Available over native gRPC and gRPC-web.
Auth: Bearer session.
Errors: Outcomes arrive in the stream, as for RunFetch. The stream can end with an error only if forwarding to the runner fails in transport.

Runs the same pipeline and streams real progress as each phase completes: data_health, rules, scenarios, recommendations, and a terminal final event that carries the full RunFetchResponse in result. A budget refusal is a single denied event with done: true. An identical recent request may be answered straight from a cache with one final event (“Analysis complete (cached)”), and the result’s provenance then says so.

Response: RunFetchUpdate

Field	Type	Description
`phase`	`string`	`data_health`, `rules`, `scenarios`, `recommendations`, `final`, or `denied`.
`message`	`string`	Human-readable progress, for example `Data health checked`.
`done`	`bool`	This phase, or for `final` and `denied` the whole run, is complete.
`result`	`RunFetchResponse`	Set only on the `final` event.

ListTraces

rpc ListTraces(ListTracesRequest) returns (ListTracesResponse);

Kind: Unary.
Auth: Bearer session.
Errors: FAILED_PRECONDITION if no session store is configured. INTERNAL if it cannot be read.

Lists recent fetch runs, newest first.

Request: ListTracesRequest

Field	Type	Description
`limit`	`int32`	Maximum runs. 0 or negative means 20. Capped at 200.

Response: ListTracesResponse

Field	Type	Description
`traces`	`repeated` `Trace`	One per run. `description` is `Cmd: <command> \| <first 50 characters of the analysis>`.

GetTraceDetails

rpc GetTraceDetails(GetTraceDetailsRequest) returns (GetTraceDetailsResponse);

Kind: Unary.
Auth: Bearer session.
Errors: UNAVAILABLE if no session store is configured. NOT_FOUND if the trace does not exist.

Request: GetTraceDetailsRequest

Field	Type	Description
`trace_id`	`string`	A run’s `transaction_id`.

Response: GetTraceDetailsResponse

Field	Type	Description
`trace`	`Trace`	The run. `description` holds the command, the full analysis and the generated SQL.

GenerateSOP

rpc GenerateSOP(GenerateSOPRequest) returns (GenerateSOPResponse);

Kind: Unary.
Auth: Bearer session.
Errors: INVALID_ARGUMENT if the request trips the prompt-injection check. PERMISSION_DENIED if it trips the fetch agent’s guardrail.

Drafts a standard operating procedure in Markdown on the model plane. If the model is unavailable, sop_content is SOP Generation Failed. That is not an error, so check the content.

Request: GenerateSOPRequest

Field	Type	Description
`topic`	`string`	What the procedure is for.
`process_name`	`string`	The process.
`steps`	`repeated string`	Optional step hints.

Response: GenerateSOPResponse

Field	Type	Description
`sop_content`	`string`	The procedure, in Markdown.
`sop_id`	`string`	`sop_<unix seconds>`.

Talk

rpc Talk(stream FetchServiceTalkRequest) returns (stream FetchServiceTalkResponse);

Kind: Bidirectional streaming.
Auth: Bearer session.
Errors: Always UNIMPLEMENTED. Voice runs through CallingService.

Request: FetchServiceTalkRequest

Field	Type	Description
`audio_data`	`bytes`	Audio.

Response: FetchServiceTalkResponse

Field	Type	Description
`audio_data`	`bytes`	Audio. Never returned.
`text`	`string`	Text. Never returned.

ListFetchStarters

rpc ListFetchStarters(ListFetchStartersRequest) returns (ListFetchStartersResponse);

Kind: Unary.
Auth: Bearer session.
Errors: None.

Returns four suggested prompts, sampled from the deployment’s configured list or from a built-in list.

Request: ListFetchStartersRequest

No fields.

Response: ListFetchStartersResponse

Field	Type	Description
`starters`	`repeated` `FetchStarter`	Suggestions.

Messages

FetchAnalysisResult

Field	Type	Description
`transaction_id`	`string`	Run id.
`sql_generated`	`string`	The SQL the pipeline generated and ran.
`quality`	`DataQuality`	Not measured by the current pipeline: every figure is 0. See `metrics.unmeasured_reason`.
`profiling`	`DataProfiling`	Only `data_shapes` is set, and it is a fixed label. The other fields are empty.
`metrics`	`EvaluationMetrics`	No evaluation harness runs for a fetch: `unmeasured_reason` is set and every score is absent. Do not display them.
`graph_nodes`	`repeated` `KnowledgeGraphNode`	The domain graph.
`graph_edges`	`repeated` `KnowledgeGraphEdge`	Its edges, with the evidence in `relation`.
`analysis_text`	`string`	The business analysis, as prose.
`decisions`	`repeated` `Decision`	The twin’s decisions.
`action_cards`	`repeated` `ActionCard`	Proposed actions, with origin stage `fetch`. Decide them with `TwinsService/ExecuteAction`.
`time_series`	`repeated` `TimeSeriesInsight`	Time-series insights.
`shadow_search`	`repeated` `ShadowSearchResult`	Public research used.
`spoken_response`	`string`	A short spoken-style summary.
`provenance`	`Provenance`	How this result was produced: fresh, cached, or degraded.
`hypothesis_scenarios`	`repeated` `DecisionScenario`	The hypothesis swarm’s scenarios. A union of independent agents’ answers, not a consensus.
`hypothesis_impacts`	`repeated` `ImpactSimulation`	Swarm impacts.
`hypothesis_traces`	`repeated` `EvidenceTrace`	Swarm evidence traces.
`hypothesis_forecasts`	`repeated` `TimeSeriesForecast`	Swarm forecasts.
`hypothesis_anomalies`	`repeated` `TimeSeriesAnomaly`	Swarm anomalies.
`hypothesis_scenarios_inferred`	`int32`	Scenarios the estate proposed before the agent cap. Meaningful only when `hypothesis_swarm_ran` is `true`.
`hypothesis_agents_dispatched`	`int32`	Agents started. Fewer than inferred means the lists above are a sample.
`hypothesis_agents_succeeded`	`int32`	Agents that produced a simulation.
`hypothesis_swarm_ran`	`bool`	Whether the three counts above were measured. `false` means they are absent, not zero: for example on a `session_eda` fetch.
`source_notices`	`repeated string`	Sentences about sources that could not be read, or about where a source’s SQL ran. Empty does not mean everything was fine.
`action_judgements`	`JudgementSet`	The verdict on every action proposed in this run, accepted and rejected. Rejected actions appear nowhere else.

DataQuality

Field	Type	Description
`accuracy`	`double`	Accuracy.
`completeness`	`double`	Completeness.
`consistency`	`double`	Consistency.
`timeliness`	`double`	Timeliness.
`validity`	`double`	Validity.
`uniqueness`	`double`	Uniqueness.
`integrity`	`double`	Integrity.
`relevance`	`double`	Relevance.

DataProfiling

Field	Type	Description
`outliers`	`repeated string`	Outliers.
`patterns`	`repeated string`	Patterns.
`schema_drifts`	`repeated string`	Schema drifts.
`data_shapes`	`string`	Data shapes.
`duplicate_rows`	`int32`	Duplicate rows.

Provenance

Field	Type	Description
`path`	`string`	How the result was reached, for example `exact-cache`, `near-dup` or `full`.
`model`	`string`	The model that produced it. Empty for a cache or deterministic result.
`source`	`string`	`fresh`, `exact-cache`, `near-dup` or `offline`.
`degraded`	`bool`	Produced without full server capability.
`confidence`	`double`	Judge score or near-duplicate similarity, 0 to 1.
`computed_at`	`int64`	Unix seconds when the underlying value was produced. Use it to judge staleness.

Trace

Field	Type	Description
`id`	`string`	The run’s transaction id.
`schema_name`	`string`	Always `execution_log`.
`table_name`	`string`	Always `session_result`.
`row_count`	`int64`	Not populated.
`size_bytes`	`int64`	Not populated.
`last_modified`	`string`	When the run was recorded, RFC 3339.
`description`	`string`	The run’s command and analysis. See each RPC.
`freshness_label`	`string`	Not populated.
`columns`	`repeated string`	Not populated.
`downstream_tables`	`repeated string`	Not populated.

FetchStarter

Field	Type	Description
`icon`	`string`	Icon name.
`title`	`string`	Title.
`subtitle`	`string`	Subtitle.
`prompt_text`	`string`	The prompt to send as `RunFetchRequest.command`.

Enums

RunFetchRequest.TriggerType

Value	Meaning
`TRIGGER_TYPE_UNSPECIFIED`	Not set.
`TRIGGER_TYPE_MANUAL`	Started by a person.
`TRIGGER_TYPE_SCHEDULED`	Started by a schedule.
`TRIGGER_TYPE_API`	Started by an integration.

Configuration, connections & runners Twins, simulation & claims