Omni

Starts the full Omni AI agent on an open-ended or multi-step analytical question and returns immediately with a 'jobId' — it does NOT wait for or return the answer, which is retrieved separately once the job finishes. Use this (not getData) for anything needing planning, several queries, or a reasoned written answer: deep analysis ("what's driving the revenue drop"), investigations ("investigate churn last quarter"), building dashboards and reports, creating visualizations and forecasts, and editing the semantic model. The job runs asynchronously and can take minutes; the response carries 'jobId', 'conversationId', and status:"submitted". Poll checkStatus with the jobId for progress and the answer. To ask a follow-up in the same thread, pass the returned conversationId back in. If modelId was not configured via headers you must pass it. topicName is optional — omit it to let the agent pick.

askOmni

Polls a dashboard download started by startDashboardDownload. Returns the job's status — "in_progress" while it renders, "complete" once the render finished, or "error" with the reason (format is omitted on error) — plus when it was created. "complete" does not mean every tile made it: a tile whose query failed renders empty without changing the status, so say the render may be missing tiles rather than asserting it is whole. A render usually takes seconds to a couple of minutes depending on the dashboard's queries, so wait a few seconds between polls. Once complete, call fetchDashboardDownload with the same identifier and jobId to get the file. The job belongs to the user who started it, so a jobId started as another user is not found.

checkDashboardDownload

Checks on a job started by askOmni and returns quickly. Pass the jobId. While the agent is still working it returns { status: "running", state, progress } — progress.message is what it's doing right now (e.g. "Generating 3 queries"), and the result includes an 'instructions' field telling you what to relay to the user (and to stay quiet when the step is unchanged). Once it's done it returns the full answer: the final markdown 'message', the 'topic', an 'omniChatUrl' (always show it to the user), the 'conversationId' (pass back to askOmni for a follow-up), and a compact 'actions' list. A failed job returns an error; a cancelled job returns status:"cancelled". This is a fast status check — call it again whenever you want a fresh update; you decide how often to poll until it reaches a terminal result. Agentic jobs routinely run for several minutes; that is normal, not a failure — keep polling and don't give up (or tell the user it failed) just because it's still running after a few minutes.

checkStatus

Returns the file a completed dashboard download produced — the job from startDashboardDownload once checkDashboardDownload reports it "complete" — after a text block with its size: a png as an image you can look at, a pdf as an embedded application/pdf resource. A pdf up to 30 MB and a png up to 10 MB come back; past that the response says what to do instead (a pdf render for an oversized png). Calling this before the job completes is not an error state to retry blindly: it reports that the job is still in progress, so poll checkDashboardDownload first.

fetchDashboardDownload

Gets data by generating and executing a query from natural language. Use this when the user has a question that is asking for data. For example, "how many users do I have?", "what was sales like last month?". Keep the user's own wording where it carries meaning: qualifiers and filter conditions are read straight from the prompt, and relative dates like "last month" or "yesterday" are resolved server-side, so don't convert them to absolute dates. If a user provides SQL, study it, be succinct, and convert it to a plain english question describing what data the SQL is querying, then call this tool with that description as the prompt. The topicId is optional and rarely needed — omit it and the server picks the most appropriate topic for the prompt automatically (or surfaces a non-topic view when the server is configured for all-views-and-fields mode). Pass it only to scope the query to a topic you already have. If modelId was not configured via headers, you must pass it as a parameter (call pickModel first to see available models). Defaults to 1000 rows unless the prompt specifies a count; rowLimitHit: true in the response means the result is partial — say so, and re-ask with a row count if more are needed. The tool returns: 1. JSON Query results, (optional) 2. The filters applied to the query, (optional) 3. A workbook URL to view the full analysis within the Omni application -- If a workbook URL is present, always show it to the user. The response also includes 'topic' (real topic name, or null) and 'baseView' (base view name when queryAllViews surfaced a non-topic view, or null) — exactly one is non-null when a query was generated.

getData

Alpha — the app content shape may change without a deprecation cycle. Reads the published content of an Omni app document behind an identifier: the complete HTML the app renders from, plus its sandbox settings. This is the app's whole artifact, often hundreds of kilobytes of HTML with no upper bound on read, so it is a real context cost: read one app at a time, once you know which one you need to understand or reason about. Whether a document is an app is not discoverable up front — a document that presents a dashboard, a report, or nothing answers 404, as does any app when the org has apps disabled, and that 404 is the cheap way to find out. The content is the published version; edits sitting in a draft are not included.

getApp

Alpha — the app content shape may change without a deprecation cycle. Reads the unpublished content of an Omni app document's main draft: the complete HTML and sandbox settings as they stand after any writes not yet published, including work other editors have saved to the same draft. This is what an app write edits, so read it before composing a change. A 404 carries a `detail` saying which state the document is in: 'This document has no main draft.' means no draft exists and getApp's published content is the current state; 'This draft has no app.' means the draft exists and its app was removed on it, a pending change that publishing makes live — report that state to the user and confirm before writing any content back. Like getApp, the read is the whole artifact with no upper bound, and a dashboard or a report answers 404 with its own detail.

getAppDraft

Returns a list of models available to the current API key. Each model has an id, a name, a modelKind, and — for a SHARED_EXTENSION — the baseModelId of the model it extends. An extension layers its own topics and fields on top of its base model and is queried exactly like any other model, so pick whichever one fits the question. Use this tool to discover which models are available before calling pickTopic or getData. For admin API keys, this returns all models in the organization. For user-scoped API keys, this returns only the models the user has access to. After calling this tool, select the most appropriate model for the user query and use its id when calling pickTopic and getData.

pickModel

Lists the branches of a model, each with its 'id', 'name', and 'updatedAt'. Pass a branch's id as askOmni's branchId to work on that branch: queries run against it, model edits land there instead of in a new branch, and any dashboard or app built in the same turn is generated against it. Returns an empty list when the model has no branches.

listBranches

Reads an organization's saved skills — reusable instruction sets a person wrote for the Omni agent. Start with 'list' whether the user names a handle or describes a task, then read the one you want with 'skill'. Running a skill, saving one, editing one and deleting one are all askOmni's to do — name the skill in that tool's prompt. This tool only reads, so don't carry a skill's instructions out yourself with the other tools here. The caller sees every skill in the organization when they are an organization admin, and otherwise only the ones they created. 'skill' answers 404 when no live skill has that id and 403 when it belongs to another member the caller can't see.

listSkills