TableCharts Agent API
One endpoint. Send tabular data, get a live dashboard URL back in one round-trip.
A2A-only service. No human UI for end users — this is a backend service consumed by other AI agents.
Let your agents pay automatically
When quota runs out, we return 402 Payment Required with a buy_url. Your agent pays and retries — no human loop.
import os, time, requests
ENDPOINT = "https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard"
AUTH = {"Authorization": f"Bearer {os.environ['TC_API_KEY']}"}
def generate_with_x402(payload, wallet_pay_fn, tries=3):
"""Call TableCharts; if 402, pay via buy_url and retry."""
for attempt in range(tries):
r = requests.post(ENDPOINT, headers=AUTH, json=payload, timeout=30)
if r.status_code == 402:
invoice = r.json() # {amount, currency, buy_url, nonce, ...}
settlement = wallet_pay_fn(invoice) # agent settles (Stripe or USDC)
AUTH["X-PAYMENT"] = settlement
continue
r.raise_for_status()
return r.json() # {dashboard_url, embed_iframe, ...}
raise RuntimeError("x402 retry limit exceeded")Connect TableCharts inside Grok
- Go to grok.com/connectors → New Connector → Custom
- Paste this server URL:
https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/mcp-grok- Start a new chat and turn Table Charts on.
- Ask: "Use Table Charts create_chart on this table…"
Overview
TableCharts is a Chart Generation Agent. Other AI agents send raw tabular data via REST, Google's A2A protocol, or email, and receive a live-updating dashboard URL (and iframe snippet) in one round-trip. The dashboard re-fetches its source data automatically — your agent does not need to repost.
Quickstart
Subscribe to any weekly plan (from $29/week), grab a key from /dashboard/api-keys, then paste this into your terminal.
curl -X POST https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard \
-H "Authorization: Bearer tc_live_<your_key>" \
-H "Content-Type: application/json" \
-d '{"data":[{"month":"Jan","revenue":42000},{"month":"Feb","revenue":48000},{"month":"Mar","revenue":56000}],"title":"Q1 Revenue"}'Health check: curl https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/health
Base URL
https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboardOne stable URL. Health check at https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/health.
Authentication
API key required. All /generate-dashboard calls must include Authorization: Bearer tc_live_…. Free tier includes 10 dashboards with no credit card. Paid plans start at $29/month (100 charts) or $0.59/chart via x402.
Each successful call consumes one quota slot or one prepaid top-up credit. When all are zero the endpoint returns 402 with {code:"quota_exhausted"} and a buy_url pointing to /pricing#topups. Create a key at /dashboard/api-keys (sign in first). See pricing for plans and top-ups.
curl -X POST https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard \
-H "Authorization: Bearer tc_live_..." \
-H "Content-Type: application/json" \
-d '{"data": [...]}'Get an API key at /api-keys (sign in first).
Use it as Authorization: Bearer tc_live_…
The Grok MCP endpoint uses this same key, stored server-side as the GROK_MCP_KEY secret — no key in the URL.
POST /generate-dashboard
The single endpoint. Accepts one of data, csv, or source_url.
Request fields
| Field | Type | Required | Notes |
|---|---|---|---|
| data | array<object> | one of | Flat key/value rows. |
| csv | string | one of | Raw CSV with header row. |
| source_url | string | one of | Public Notion DB, Google Sheet, or CSV URL. |
| title | string | no | Dashboard title. |
| description | string | no | Short caption shown on the embed. |
| chart_type | string | no | Override auto-selection. See below. |
Response fields
| Field | Type | Notes |
|---|---|---|
| ok | boolean | true on 200. |
| dashboard_url | string | Public embed URL. |
| embed_url | string | Alias of dashboard_url. |
| embed_iframe | string | Ready-to-paste iframe snippet. |
| embed_id | string | Stable id for later reference. |
| chart_type | string | The selected chart type. |
| rows | number | Row count after cleaning. |
Input modes
Inline JSON
{
"data": [
{ "month": "Jan", "revenue": 42000 },
{ "month": "Feb", "revenue": 48000 }
],
"title": "Q1 Revenue"
}CSV string
{
"csv": "name,score\nAlice,92\nBob,87\nCarol,75",
"title": "Team Scores",
"chart_type": "bar"
}Source URL
Supported sources: public Notion databases, public Google Sheets, public CSV URLs, and Salesforce SOQL (with a connected token).
{
"source_url": "https://www.notion.so/<workspace>/<database-id>",
"title": "Roadmap Status"
}Chart types
Auto-selection picks one for you. To override, set chart_type to any of:
Code examples
import os
import requests
api_key = os.environ["TABLECHARTS_KEY"]
r = requests.post(
"https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard",
headers={"Authorization": f"Bearer {api_key}"},
json={
"data": [
{"month": "Jan", "revenue": 42000},
{"month": "Feb", "revenue": 48000},
{"month": "Mar", "revenue": 56000},
],
"title": "Q1 Revenue",
},
timeout=30,
)
print(r.json()["dashboard_url"])const res = await fetch("https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${process.env.TABLECHARTS_KEY}`,
},
body: JSON.stringify({
data: rows,
title: "Q3 Pipeline",
chart_type: "bar",
}),
});
const { dashboard_url, embed_iframe } = await res.json();import os
from langchain_core.tools import tool
import requests
@tool
def generate_dashboard(data: list[dict], title: str = "Dashboard") -> str:
"""Send tabular data to TableCharts; returns a live dashboard URL."""
r = requests.post(
"https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard",
headers={"Authorization": f"Bearer {os.environ['TABLECHARTS_KEY']}"},
json={"data": data, "title": title},
timeout=30,
)
r.raise_for_status()
return r.json()["dashboard_url"]import os
from crewai_tools import tool
import requests
@tool("TableCharts Dashboard")
def tablecharts(data: list[dict], title: str = "Dashboard") -> str:
"""Turn a list of row dicts into a live dashboard URL."""
r = requests.post(
"https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard",
headers={"Authorization": f"Bearer {os.environ['TABLECHARTS_KEY']}"},
json={"data": data, "title": title},
timeout=30,
)
return r.json()["dashboard_url"]{
"type": "function",
"function": {
"name": "generate_dashboard",
"description": "Generate a live, embeddable dashboard from tabular data.",
"parameters": {
"type": "object",
"properties": {
"data": { "type": "array", "items": { "type": "object" } },
"csv": { "type": "string" },
"source_url": { "type": "string" },
"title": { "type": "string" },
"chart_type": { "type": "string", "enum": ["bar","line","area","pie","doughnut","radar"] }
}
}
}
}Ready-to-use examples
Full working tool nodes for the two most common agent frameworks. Each snippet uses realistic revenue data, reads the X-Chart-Billing response header for observability, and includes a hook for the x402 retry flow.
Billing behavior: Agents automatically use prepaid credits (or an active subscription) first, then fall back to $0.59 per chart via x402 when the quota is exhausted. See the x402 guide for the full pay-then-retry pattern.
"""LangGraph tool node — TableCharts dashboard generator.
Agents automatically use prepaid credits first, then fall back to
$0.59 per chart via x402 when the quota is exhausted.
"""
import os
import requests
from typing import TypedDict, Annotated
from langgraph.graph import StateGraph, END
from langgraph.prebuilt import ToolNode
from langchain_core.tools import tool
API_URL = "https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard"
class AgentState(TypedDict):
rows: list[dict]
title: str
dashboard_url: str | None
billing_source: str | None # subscription | prepaid | trial | x402
@tool
def tablecharts_dashboard(rows: list[dict], title: str = "Dashboard") -> dict:
"""Turn a list of row dicts into a live TableCharts dashboard URL."""
r = requests.post(
API_URL,
headers={"Authorization": f"Bearer {os.environ['TABLECHARTS_KEY']}"},
json={"data": rows, "title": title},
timeout=30,
)
# On 402, hand off to the x402 pay-then-retry helper (see /x402 docs).
if r.status_code == 402:
raise RuntimeError("quota_exhausted — run x402 pay+retry loop")
r.raise_for_status()
body = r.json()
return {
"dashboard_url": body["dashboard_url"],
# Observability: which credit bucket paid for this chart.
"billing_source": r.headers.get("X-Chart-Billing", "unknown"),
}
def chart_node(state: AgentState) -> AgentState:
result = tablecharts_dashboard.invoke(
{"rows": state["rows"], "title": state["title"]}
)
return {**state, **result}
graph = StateGraph(AgentState)
graph.add_node("chart", chart_node)
graph.set_entry_point("chart")
graph.add_edge("chart", END)
app = graph.compile()
# ---- Example run --------------------------------------------------------
sales = [
{"month": "Jan", "revenue": 42000},
{"month": "Feb", "revenue": 48000},
{"month": "Mar", "revenue": 56000},
{"month": "Apr", "revenue": 61500},
]
final = app.invoke({"rows": sales, "title": "Q1 Revenue", "dashboard_url": None, "billing_source": None})
print(final["dashboard_url"], "· billed via:", final["billing_source"])"""CrewAI custom Tool — TableCharts dashboard generator.
Agents automatically use prepaid credits first, then fall back to
$0.59 per chart via x402 when the quota is exhausted.
"""
import os
import requests
from typing import Type
from pydantic import BaseModel, Field
from crewai import Agent, Task, Crew
from crewai.tools import BaseTool
API_URL = "https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard"
class TableChartsInput(BaseModel):
rows: list[dict] = Field(..., description="Row objects with consistent keys.")
title: str = Field("Dashboard", description="Human-friendly dashboard title.")
class TableChartsTool(BaseTool):
name: str = "tablecharts_dashboard"
description: str = (
"Generate a live, embeddable dashboard URL from tabular sales/revenue "
"data. Returns the dashboard URL and the billing source header."
)
args_schema: Type[BaseModel] = TableChartsInput
def _run(self, rows: list[dict], title: str = "Dashboard") -> str:
r = requests.post(
API_URL,
headers={"Authorization": f"Bearer {os.environ['TABLECHARTS_KEY']}"},
json={"data": rows, "title": title},
timeout=30,
)
# On 402, run the x402 pay-then-retry helper (see /x402 docs).
if r.status_code == 402:
return "ERROR: quota_exhausted — run x402 pay+retry loop"
r.raise_for_status()
body = r.json()
billing = r.headers.get("X-Chart-Billing", "unknown")
return f"{body['dashboard_url']} (billed via: {billing})"
# ---- Example crew -------------------------------------------------------
analyst = Agent(
role="Revenue Analyst",
goal="Visualize quarterly sales for the exec review.",
backstory="A pragmatic FP&A analyst who prefers pictures over pivot tables.",
tools=[TableChartsTool()],
)
sales = [
{"quarter": "Q1", "revenue": 156000},
{"quarter": "Q2", "revenue": 189000},
{"quarter": "Q3", "revenue": 214500},
{"quarter": "Q4", "revenue": 267000},
]
task = Task(
description=f"Chart this revenue data and return the dashboard URL: {sales}",
expected_output="A TableCharts dashboard URL.",
agent=analyst,
)
crew = Crew(agents=[analyst], tasks=[task])
print(crew.kickoff())A2A protocol
Agent Card is published at /.well-known/agent-card.json. Orchestrators following Google's A2A spec can discover skills, input modes, and pricing automatically.
Primary skill id: generate_dashboard.
{
"jsonrpc": "2.0",
"method": "tasks/send",
"params": {
"id": "task-001",
"skill": "generate_dashboard",
"message": {
"role": "user",
"parts": [{
"kind": "data",
"data": {
"data": [{ "month": "Jan", "revenue": 42000 }],
"title": "Q1 Revenue"
}
}]
}
}
}Email trigger
Send a CSV/JSON attachment or a Notion/Sheets link to charts@tablecharts.co. The reply contains the dashboard URL within ~10s. Sender must be registered.
Errors
| Status | Meaning |
|---|---|
| 400 | Bad input — missing or invalid data/csv/source_url. |
| 401 | Invalid Bearer token. |
| 402 | Quota exhausted. Response includes code:"quota_exhausted" and buy_url. |
| 429 | Rate limit exceeded. |
| 500 | Internal — safe to retry once with backoff. |
{ "error": "Provide one of: data (array), csv (string), or source_url (string)" }Rate limits
| Tier | Limit |
|---|---|
| Authenticated (key) | 1,000 / hour / key (subject to monthly quota) |
| Starter Monthly | 100 dashboards / month, $0.49 overage |
| Pro Monthly | 400 dashboards / month, $0.39 overage |
| x402 (agents) | $0.59 USDC per chart · no signup |
| Prepaid bundles | 15 / 60 / 200 / 600 credits — never expire |
Webhooks & polling
Dashboards with a source_url auto-refresh server-side. If your downstream agent needs change detection, poll the embed URL on a cadence (every 5–15 min is typical) and diff the returned snapshot. Native webhook callbacks are on the roadmap.
Best practices
- Cache
dashboard_urlper logical dataset to avoid duplicate generation. - For recurring datasets, prefer
source_urlso the dashboard stays live. - Always set
title— it becomes the embed page title and improves shareability. - Use
chart_typeonly when your agent has strong intent — auto-selection usually wins. - Embed the iframe with
sandbox="allow-scripts allow-same-origin"if rendering inside another agent UI.
Billing
Pay via Stripe Checkout — see /pricing:
- Subscriptions — $29/mo (100 charts, $0.49 overage) or $79/mo (400 charts, $0.39 overage). Included quota resets monthly.
- Prepaid bundles — one-time $9 / $29 / $79 / $199 for 15 / 60 / 200 / 600 credits. Stack on any subscription, never expire.
- x402 (agents) — $0.59 USDC on Base per successful chart. No signup, agent pays automatically.
Agents & bundles: when an agent calls /generate-chart with Authorization: Bearer tc_live_…, we draw from the account's subscription quota and prepaid bundle credits first, and only fall back to $0.59 x402 per chart once both are exhausted. Every response includes an X-Chart-Billing header (weekly, prepaid, trial, or x402) so agents can observe how they were charged.
When weekly quota is exhausted, calls fall through to top-up credits. When both are zero, the endpoint returns 402 quota_exhausted with a buy_url pointing to /pricing#topups. Failed calls (4xx/5xx) never consume credit.
Changelog
- v1.1 — paid-only API. Bearer key required on every call. Weekly subscriptions + stackable top-ups. New 402 quota_exhausted response.
- v1 — REST + A2A + email triggers, 15 chart types.