Data Agent API: HTTP and SSE for Long Tasks (2026)

By William Zhu & the InfiniSynapse Data Team · Published: 2026-08-22 · Last updated: 2026-08-24 · Last verified: 2026-08-24 · Next review: 2026-11-24 · Editorial standards · Corrections

Table of Contents

• TL;DR
• What a data agent API actually starts
• A contract framework for HTTP plus SSE
• Why a sync answer endpoint is the wrong shape
• Tool landscape around the same task id
• Implementation steps from console proof to product call
• Desk sample: explain-this-metric from a backend (illustrative)
• Selection scorecard
• Failure modes that break the API contract
• Frequently Asked Questions
• Conclusion

TL;DR

We evaluate these patterns at the InfiniSynapse desk on sanitized composites; sample figures on this page are illustrative, not customer uplifts.

Direct answer: A data agent api starts the same long task the web console already shows. HTTP creates the job and returns an id. SSE (or polling) reports plan, SQL, and files. /tasks remains the audit console. Do not treat a sync JSON answer as the contract.

What you'll learn:

• What a data agent api owns versus what your product UI owns
• Why HTTP create plus SSE status survives warehouse scans that a 2-second ChatBI box cannot
• How the same task id appears in the web console, your backend, and the CLI
• An illustrative desk composite of an in-app “explain this metric” call
• Failure modes: browser keys, dual timelines, and blocking the user request on the job

The hub for embedding a data analyst in an existing product is the product picture. This page is the wire: a data agent api, without a second warehouse.

What a data agent API actually starts

Key Definition: A data agent api is the HTTP-and-SSE contract that creates a long analysis task on sources you authorize, streams steps as they happen, and writes the same plan, SQL, and downloadable artifacts the web console already shows. It is not a sync ChatBI reply and not a key you paste into a browser.

Product teams hear “API” and picture POST /ask returning a paragraph. That picture fails for analysis. A data agent plans, queries, retries, and writes files. Those steps outlast a checkout timeout, so a data agent api returns a task id first. The paragraph, if you show one, is an artifact you open later.

The durable object is the task. Document-oriented database storage is a reminder that the record is a document with a life cycle—plan, steps, files—not a one-line scalar. A data agent api that only returns a string has already thrown that document away.

If the missing object is duration rather than the wire, continue in the long-task agent layer. If the next failure is the host UI, use analyze inside your app.

OECD’s AI policy portal is independent context for putting an automated analyst behind a product you already ship: purpose limitation, human oversight, and a trail someone can reopen. A data agent api keeps that trail when the caller is a server, not a person clicking Chat.

The task id is the object you store

Your backend stores four fields: tenant, requester, task id, and a small status enum. That is enough for support to reconstruct the job. Caching the final paragraph in your own database creates a second, drifting transcript. Store the id. Open /tasks when a human needs SQL.

Keys stay on the server that calls it

Issue the key in the web task console. Hold it in your backend secret store. The host browser never sees it. A key in a single-page app is a published key, even if you “obfuscate” it. Silent partner setup can create the tenant without emailing secrets; that path is still a server path.

A contract framework for HTTP plus SSE

Three objects stay distinct. Collapsing them is how a data agent api becomes a chat widget with extra JSON.

W3C DCAT 3 is the independent catalog model for a dataset you can name, fetch, and cite. Treat the task the same way: a cataloged job with distributions (memo, chart, extract), not an anonymous bubble. If a reviewer cannot open those distributions, the data agent api is unfinished.

Create is short; the job is long

POST creates the task and returns the id in well under a second in a healthy desk composite (illustrative, not an SLA). The warehouse scan still takes minutes. SSE tells the UI the plan started, a query retried, and a file appeared. Polling is acceptable if your edge cannot hold an SSE socket. Either way, do not hold an HTTP worker until the PDF exists.

Apache Kafka documentation is the right contrast, not the required bus. Kafka fans out events to many consumers. A product user watching one job needs a single stream. Use Kafka when many services must react. Use SSE on the data agent api when one client needs one timeline.

Why a sync answer endpoint is the wrong shape

A sync “ask → JSON answer” looks easy to ship. It dies on scans, retries, and chart files. You will add timeouts, then caches, then a fake number. Natural language to SQL as a single round trip has the same failure mode. Use it for tiny, already-warm queries if you must. Do not hide analysis behind that shape and still call it a data agent api.

Chat with your data is a valid human door. It is not a latency budget. When the same goal must run from a product backend, the data agent api starts a long task and the human door still opens the same id in /tasks.

Same job, two doors

The durable method: create the job in the web console first, then call the same shape from your server. The user sees a task id in your UI. An analyst opens the same id in the console. When both doors share one timeline, pairing and support stop arguing about which transcript is true. Self-service analytics still applies: the operator types a business question. Your UI is the form.

Tool landscape around the same task id

You can reach a data agent api from a product backend, from agent_infini in an IDE, or from a protocol adapter. The audit object should not change.

MCP for data analysis can expose tools to an IDE. It does not replace a data agent api in a shipped product. If you only have MCP and no console, you will debug from chat logs.

If the host product already queries ClickHouse for tiles, that OLAP path is still a query path. The data agent api is the analysis path: plan, retries, memo, chart. Tiles and long tasks are different objects. Dashboard artifacts can be files the task writes; they are not a substitute for the id.

InfiniSynapse’s fit is that layer: create a key in the task console, call HTTP from your server, stream status, and open the same timeline. Prove the path on the web tool first.

HTTP, SSE, and the CLI share one console

Server HTTP starts the task. SSE reports steps. The CLI is another door—the task still appears in the web console. A private log your analysts cannot open is a second product. Support will pick the prettier one and lose the SQL.

Implementation steps from console proof to product call

Do not point production traffic at a data agent api on day one. Prove the job where a human can open every step.

1. Authorize a sanitized source in the web console.
2. Ask the exact goal your in-app button will send.
3. Open the plan, SQL, and files. If that run is not acceptable, the API will not make it acceptable.
4. Create a key in /tasks. Store it on the server. Never paste it into a README, email, or SPA.
5. Your UI posts the goal and tenant context to your backend. The backend calls the data agent api and returns the id.
6. The UI shows “running” and a link. Notify on ready or failed. Download artifacts from the workspace.

Prove the task before you write the client

The cheapest data agent api test is a console run. If the SQL is wrong in /tasks, a prettier spinner will not fix it. Data governance reviewers should open the same task the product will call.

Call from the backend, review on one timeline

Map errors to your own status page, not to a raw model dump. If you then copy only the final paragraph into your app, you threw away the audit. Success is support clicking from your admin into the same task and seeing the same SQL.

Desk sample: explain-this-metric from a backend (illustrative)

Desk composite, illustrative, not a latency SLA. Host app: an internal admin. Button: “Explain this metric” on a contribution tile. The app sent the metric id, the date range on screen, and the source id. The backend called a data agent api. The UI showed a task id in under a second. The job ran for minutes, wrote a Markdown memo and a chart, and the same id appeared in the web console.

An analyst opened the SQL and confirmed the date filter matched the tile. A 30-second sync call would have timed out on the warehouse scan. The long-task shape made the button honest. Persist four fields: tenant, requester, task id, and status. Ready means files exist and SQL opened.

Figure. Desk composite from this page: Admin “Explain this metric”; API returned task id; analyst opened SQL in console. Published context: en.wikipedia.org; clickhouse.com; oecd.ai. Not a customer experiment, SLA, or official benchmark.

Desk composite: in-app Explain this metric; task id in <1s, job minutes.

We ran this check on a sanitized composite at the InfiniSynapse desk on 2026-08-23. The backend called a data agent api and stored tenant, requester, task id, and status. We opened /tasks on that id and confirmed SQL matched the tile before keeping the memo. Figures stay illustrative. What you can copy is the create-then-poll contract, not a finish-time promise.

Selection scorecard

Score a candidate the way you would score a job queue, not a chatbot.

If a vendor cannot show the same task from a data agent api and from the web console, you are buying two products.

Failure modes that break the API contract

Most failures are contract-shape failures, not model failures.

Blocking the user request on a long job

A spinner that lasts as long as a warehouse scan trains users to click away. Return a task id. Notify when artifacts are ready.

Dual timelines that disagree

The app stores a summary. The console stores SQL. They diverge after the first retry. You no longer have an audit.

Shipping the key to the browser

Obfuscation is not a control. A product path without a backend hop is how keys leak.

Before you write integration code, run the exact in-app goal in the web console, write down the task id, and confirm you can open SQL and a file. If that proof fails, you are not ready to call a data agent api from production.

Route the diagnosis to the live guide that owns the next object.

Run the job in the console, then call the same API

Ask the in-app goal on an authorized source, open the task steps, and only then call that same task shape from your backend. This check uses only sources you authorize.

Commercial association: You do not need the workspace to complete the educational diagnosis on this page.

Open InfiniSynapse

Use only authorized, sanitized data. Do not paste secrets.

How this page is sourced. William Zhu is cofounder of InfiniSynapse (GitHub @allwefantasy); no personal LinkedIn is published. Desk experience: designing and reviewing production analysis packs—definition locks, read-only source binds, and downloadable /tasks artifacts. Reviewed by analytics engineering · data platform · LLM security · editor. Editorial standards · corrections · publishing principles · Contact zhuhl@infinisynapse.com. Company Vision. COI: InfiniSynapse sells an AI-native Data Agent; the in-article banner is a commercial association. Fact-check: Wikipedia · oecd.ai · w3.org · kafka.apache.org · ClickHouse documentation.

Frequently Asked Questions

Is a data agent api the same as a ChatBI ask endpoint?

Bottom line: No. A ChatBI ask endpoint tries to return a paragraph inside one HTTP timeout. The long-task contract creates a job, streams steps, and keeps /tasks as the audit console.

Can the browser hold the key if I obfuscate it?

Bottom line: No. Keys stay on the server that calls the data agent api. Obfuscation is not a control. A path without a backend hop is how keys leak.

Do I need SSE, or is polling enough?

Bottom line: Either can report status. SSE is the natural stream for one client watching one job. Polling is fine if your edge cannot hold the socket. The data agent api still returns a task id first.

Does the API write back to production tables?

Bottom line: No. A data agent api reads sources you authorize and writes artifacts in the task workspace. It does not publish keys and does not auto-write a production database.

How do I know web and API ran the same job?

Bottom line: Open /tasks and look for the id your backend stored. If the console cannot show that id, you do not have a data agent api—you have two products.

Conclusion

A data agent api is HTTP to create a long task, SSE or polling to watch it, and one console to audit it. Prove the goal on the web. Call the same shape from a server that holds the key. Store the task id, not a paragraph.

Sync ChatBI is a tempting shortcut and a poor fit for scans and files. When the console run is acceptable, take the same check into InfiniSynapse and keep that timeline as the source of truth.