Administer

Control AI in a workspace

Every AI feature in DataSquares asks the workspace’s AI controls before the AI starts: the chat, Explain and Analyze, card summaries, Stories, reports, pipelines, data quality, metric digests, theme and measure drafts, Ask AI on shares and embeds, search by meaning, AI search on large models, and lineage explained. One set of controls decides all of them, the same way everywhere:

Is AI on in this workspace, and is this feature on?
Does the person’s role include this feature?
Is a monthly AI credit budget used up?

A company administrator sets them under Administration → AI (/admin/settings/ai). Until someone changes something, there is no budget and every switch is on. Two things change by themselves when these controls arrive. A role now needs its AI Chat permission for every AI feature, not only the chat, and the built-in Viewer starts with AI chat, Explain and Analyze, Reports and Metric digests: so every AI feature of a role without AI Chat, and a Viewer’s other AI features (such as the grounded proposal in a Story review), stop until an administrator allows them (Choose who may use AI). And a question on a shared link or an embed now runs on behalf of the person who shared it, so a share made by a Viewer, by someone whose role has no AI Chat permission, or by someone who has since left the workspace stops offering Ask AI, shares made before the change included. See Ask AI on a share and the release note, which says how to bring one back. A change on this page reaches every AI feature within half a minute.

The same page holds the AI assistant’s own settings (how carefully it works, its longest answer and how long conversations are kept), the tools it may use and what people said about its answers: every AI setting of the workspace is in one place. See Workspace settings.

Turn AI off for the workspace or for one feature

The AI in this workspace card has one switch for the whole workspace, Use AI in this workspace, and one switch for each AI feature. A switch applies to this workspace only; the company’s other workspaces keep their own.

Feature	What it covers
AI chat	Questions in the chat, and the follow-up suggestions, drafts and builds it makes.
Explain and Analyze	The AI paragraph in Explain this change on cards and metrics, and the explanation Analyze writes.
Card summaries	Summarize with AI on a dashboard card.
Stories	The writing aids in Stories: rewrite, outline, next section, refreshed wording and the grounded review.
Reports	The AI summary of a report comparison, and AI layout suggestions for paginated reports.
Pipelines	Suggest recipe: transform steps written from a description. Suggest mapping: an activation’s columns matched to the keys its destination takes.
Data quality	The AI ranking and wording of a profiling scan’s findings, and Describe the check: a check drafted from a sentence, saved only when you save it.
Metric digests	The AI sentence for each metric in a scheduled digest, written for the digest’s owner.
Theme drafts	Draft with AI in the theme editor.
Measure drafting	Draft with AI for SquareX measures.
Ask AI on shares and embeds	Ask AI on shared links and embedded views. This workspace’s AI credits pay for every question.
Search by meaning	Search by meaning in the command palette. Without it, search matches words. A server that does not run search by meaning marks it Not set up on this server.
AI search	Finding the tables a question needs on a model of several hundred tables, and keeping the AI catalog of your models up to date (AI search on large models). It covers the schema finder too, where the server turns it on, and Explore this model in Prep for AI, where the server turns it on. Without it, the AI reads a large model the way it reads a small one (how much at once), and the catalog is deleted. Roles don’t decide it: its switch and the budgets do. A server that does not run AI search marks it Not set up on this server.
Description drafts	Draft with AI in Prep for AI: drafts of a model’s missing table and field descriptions, which an editor reviews before anything is published. And Describe with AI in the Catalog and on a metric: drafts of a dashboard’s or a metric’s missing description, which someone who may edit it approves before it is saved.
Governance	The AI paragraph that explains the lineage of a dashboard, a card or a metric in the Catalog, from its source on. Lineage is on Business and Enterprise. The built-in Viewer role doesn’t have this feature until an administrator allows it; every other role with AI Chat has it (Choose who may use AI).
Presentations	Draft from data: an outline, then slides, written by the AI from figures read with the person’s access, every figure on the slides live; and on a slide, Suggest a headline and Write speaker notes, from the slide’s own figures. The built-in Viewer role doesn’t have this feature until an administrator allows it; every other role with AI Chat has it.

When a feature is off:

Features that are only AI (the chat, card summaries, Stories’ writing aids, report suggestions, Suggest recipe, Suggest mapping, Describe the check, a lineage explanation, theme, measure and description drafts, and Draft from data, Suggest a headline and Write speaker notes in Presentations) refuse the request before any work, with a message that says AI is turned off for that feature.
Features where AI is one step of an answer keep the rest of the answer and leave the AI step out: Explain this change still shows the drivers it computed, Analyze its statistics, a report comparison its calculated evidence and a Story’s Review numerical claims its checked evidence; a profiling scan keeps its rule-based findings, a digest keeps its plain sentence, and search falls back to matching words. When you asked for the AI step (Explain with AI on a card or a metric, Analyze’s Phrase it, Include an AI summary on a comparison, Generate grounded proposal in a review), the answer says why it was left out: see What people see.
Ask AI on shares and embeds: viewers of a shared link or an embed no longer see the Ask AI button, a question already typed is refused, and a share’s Ask AI for viewers toggle can’t be turned on until the feature is back. A share whose Ask AI was already on keeps its switch on and says Paused where its publisher looks (the dashboard’s Share dialog lists their links under Your links to this dashboard): viewers are offered Ask AI again, with nothing to turn back on, once the feature is. Turning a share’s Ask AI off always works. The switch that counts is the one in the workspace the shared dashboard or report is in, whichever workspace the person sharing it is signed in to.
The Android app doesn’t offer Ask AI while AI or AI chat is off.

Turning Use AI in this workspace off turns every feature off at once and keeps each feature’s own switch for when AI comes back on.

AI search on large models

Under the features, the AI search on large models card shows the AI catalog of the workspace: the documents it holds, the 100,000 included, what the rest use a month in whole AI credits, and, when it waits, why. It lists the models large enough for AI search, and has two switches, both on until you change them:

Search by meaning: off, the catalog is searched by words and names only.
Value hints: off, no stored values of code lists, and no key values to match joins from, are read from your sources for the AI, and the ones kept are deleted (value hints, joins matched from values). The schema finder’s checks of your data stop too.

Which tables and fields the AI may use is set on each model, with its AI scope, and Prep for AI shows how ready each model is for the AI.

Choose who may use AI

The Who may use AI card lists each role with a checkbox for each AI feature.

A role uses AI only with its AI Chat permission. A role without it uses no AI feature at all, and its row reads No AI Chat permission: no AI. The built-in Admin, Editor and Viewer roles have it; a custom role gets it, or loses it, under Administration → Roles.
Within that permission, each role starts with these features:

Role AI features by default

Admin, Editor, and every custom role All of them

Viewer AI chat, Explain and Analyze, Reports and Metric digests
Company administrators always use every feature, whatever their role’s checkboxes say.
A change to a role applies in every workspace of your company, because roles are shared by the company’s workspaces. Setting a checkbox back to the role’s default removes the change.
Roles don’t decide search by meaning: only its switch and the budgets do. A search from the command palette counts toward the searcher’s own budget as well as the workspace’s; keeping its index up to date counts toward the workspace’s only.
A question asked on a shared link or an embed runs on behalf of the person who shared it, so their role in the shared dashboard’s or report’s workspace decides it. When their role loses Ask AI on shares and embeds, or they leave that workspace, their shares stop offering Ask AI until it’s back. The question counts toward the workspace’s budget, not theirs.
A scheduled metric digest runs for its owner, so the owner’s role is asked.
The Android app offers Ask AI only when the person’s role includes AI chat.

Role	AI features by default
Admin, Editor, and every custom role	All of them
Viewer	AI chat, Explain and Analyze, Reports and Metric digests

A feature’s own permission still applies as before: for example, Suggest recipe also needs access to the pipeline, and a card summary also needs the right to change the dashboard.

Set the company’s effort

The Effort card sets how much effort the AI puts into answers, for the whole company: every workspace of it. A change applies from the next message.

Setting	What it does	Until you change it
Default level	The effort a conversation runs at until its person chooses one. A workspace’s own Answer depth (AI settings) still sets it in that workspace. Until they choose, a much harder follow-up or a build moves the conversation up one level by itself (Effort in a conversation), never to Max and never above the highest level.	Plan default: Quick on Team, Balanced on Business and Enterprise
Highest level members may pick	The highest effort people can choose. The ones above it are shown in the chat’s Effort options, marked Not offered here, and a choice someone saved before you set it runs at the highest. No conversation moves above it by itself, and one that runs above it when you set it comes down to it, as a lower choice does.	Max (every level)
Viewers’ level	The effort for viewers, Ask AI on shared links and embedded chat. It is also the highest effort those viewers can choose, and their conversations never move above it by themselves. Above Quick only on Business and Enterprise.	Quick
Show the effort picker	Effort in Chat options, the button in the AI chat’s header. Off, every conversation runs at the default level, Effort is gone from Chat options, and the choices people saved are kept but not used until it is back on. The default level still moves a conversation up by itself as above, never past the highest level: to keep conversations from moving above the default level, set the highest level to it too.	On
Viewers may use the credits your company bought	Whether viewers keep asking the AI from the credits the company bought once their own are used up. Every viewer seat brings its holder 1,000 AI credits a month of their own, used first (Viewers’ own credits). Off, a viewer’s AI uses their own credits only, never the bought ones: a request larger than what they have left is refused, a short question asked on their last credits is not charged past them, a viewer whose own credits are used up waits for next month’s, and a viewer with no seat’s credits is refused, in every workspace whose AI runs on credits.	On

The default level and the viewers’ level can’t be above the highest level: a save that would make them so is refused, and the card offers neither above it. With the default level left on Plan default, a highest level below the plan’s default lowers it to the highest level, and the card says so: on Business with the highest level at Quick, it reads Plan default (Balanced), capped at Quick, and conversations start at Quick. On Team, a viewers’ level above Quick is refused with the Business plan’s prompt (What a Business feature looks like on Team).

Measure drafting (Draft with AI for SquareX measures) runs at its person’s effort, as the chat does, and Ask AI on shared links and embedded chat at the viewers’ level.

Set monthly AI credit budgets

Budgets are optional; there are none until you set one. The Monthly AI credit budgets card has three kinds:

Workspace budget (credits a month): the AI credits everyone in the workspace may use in a month, viewers of its shared links and embeds and its scheduled jobs included.
Budget for each person (credits a month): the AI credits each person may use in this workspace in a month.
A person’s own budget: under People with their own budget, Set a person’s budget gives one person a budget in place of the budget for each person. The trash button removes it, and the person goes back to the budget for each person.

A budget is a whole number of AI credits, from 1 to 1,000,000,000; a box left empty means no budget. Anything else is refused rather than rounded.

How budgets work:

They run by calendar month, in UTC. The card shows the credits used so far this month, and a bar for each budget.
They count every AI call’s credits, in this workspace, the same credits the AI ledger lists: runs that ended in an error, were stopped or reached their step limit count with the credits they used.
At 80%, the workspace’s administrators get a notification: once a month for each budget.
At 100%, AI pauses until the first of the next month: for that person when it is their budget, and for everyone in the workspace when it is the workspace’s. Administrators get a second notification. An AI request that already started finishes; the next one is refused, or, where AI is one step of an answer, answered without that step.
Raising or removing a budget lets AI run again within half a minute.
A budget is a limit, not a purchase. AI credits still come from your plan’s allowance and the packs you buy (see AI credits); when the credits run out, AI stops even under a budget.

What people see when AI is off or paused

The message depends on who meets it. An administrator is told where to change it; anyone else is told to ask an administrator; a viewer of a shared link or an embed is told only that Ask AI isn’t available.

Where AI is one step of an answer you asked for, the answer still comes with all its numbers, and the message takes the AI part’s place: No AI summary: (Explain with AI on a card or a metric, Analyze, a report comparison) or No AI proposal: (a Story’s review), the kind of refusal (for example Monthly AI budget reached), and the message from the table below. A review the controls refused says No AI call; no AI credits used.

When	A member sees	An administrator sees
AI is off for the workspace	AI is turned off in this workspace. Everything else keeps working; ask an administrator if you need AI.	AI is turned off in this workspace. Turn it on under Administration → AI. Everything else keeps working.
A feature is off	AI for card summaries is turned off in this workspace. Ask an administrator if you need it.	… Turn it on under Administration → AI.
The role doesn’t include the feature	Your role doesn’t include AI for pipelines. Ask an administrator if you need it.	This role doesn’t include AI for pipelines. Change it under Administration → AI.
Their own budget is used up	You’ve used your monthly AI credit budget in this workspace. AI pauses until 1 November; everything else keeps working. Ask an administrator to raise it.	… Raise the budget under Administration → AI.
The workspace’s budget is used up	This workspace has used its monthly AI credit budget. AI pauses until 1 November; everything else keeps working. Ask an administrator to raise it.	… Raise the budget under Administration → AI.
A viewer with no credits of their own left (a seat’s are used up, or they have no seat’s), while viewers may not use the credits the company bought	You have no AI credits of your own left this month, and AI for viewers from the credits your company bought isn’t turned on. Ask an administrator if you need it.	You have no AI credits of your own left this month, and AI for viewers from the credits your company bought is turned off. Turn it on under Administration → AI.

A viewer of a shared link or an embed sees Ask AI isn’t available on this view right now. in every case above, and nothing tells them which: not whether a switch, a role or a budget refused, nor when a budget resets.

If the controls themselves can’t be read for a moment, AI is refused rather than allowed: AI is paused for a moment: its settings couldn’t be checked. Try again shortly; everything else keeps working.

Through the API, each refusal has a stable code and a details object (surface, reason, and where it applies scope, resetsAt, and for an administrator actionPath):

Status	Code	When
`403`	`AI_TURNED_OFF`	AI, or the feature, is off in the workspace
`403`	`AI_NOT_ALLOWED`	The person’s role doesn’t include the feature, they aren’t a member of the workspace, or they are a viewer with no credits of their own left (a seat’s used up, or none) while viewers may not use the credits the company bought (`reason` `viewer_credits`)
`429`	`AI_BUDGET_REACHED`	A monthly budget is used up; `details.resetsAt` is when AI runs again
`403`	`AI_NOT_AVAILABLE`	Ask AI on a shared link or an embed is refused, for any of the reasons above; `details` has `surface` only
`503`	`AI_POLICY_UNAVAILABLE`	The controls couldn’t be read; try again shortly

Where AI is one step of an answer the request asked for (ai: true on POST /api/ai/explain and POST /api/ai/explain-metric, options.phrase on POST /api/ai/insights/anomalies, /influencers and /forecast, ai: true on POST /api/reports/{id}/explain-change and on POST /api/stories/{id}/analysis-review), a refusal is not an error: the answer is 200 with all its numbers, the AI step is left out (narrative is null, or narrative.status or status is unavailable), and aiRefusal carries the refusal’s code, message and details.

Read the AI ledger

The AI ledger lists every AI call in this workspace for a month:

Time, Feature, and Ran for: the person (a search from the command palette names the person searching), A viewer of a shared view for Ask AI on a shared link or an embed, The search index for keeping search by meaning’s index up to date, No person (scheduled) for a scheduled job, or A former member.
Outcome: Completed, Failed, Stopped (the person stopped it) or Step limit (it reached the most steps it may take).
Credits: the AI credits the call was charged, in whole credits: rounded to the nearest, a call charged less than half a credit reads under 1, and a call that did no AI work shows 0. Calls are counted to the thousandth of a credit, and the month’s totals add up those exact amounts before rounding once (How AI credits are counted). Every call is charged for the AI work it used, whatever its outcome.

A call that was stopped or broke off before all its AI work was reported can have a second, later line, usually within a few minutes and at most a few hours on, under the same feature and person: the credits for the rest of the work it did, once the AI service reports it. It is part of the same call, so the totals count its credits but not another call, and neither do a person’s or the workspace’s request limits. When that work can’t be read, the line shows 0 credits and nothing more is charged.

Above the list are the month’s totals, calls and credits, by feature and by person; choose a person to list only their calls. Filter by Month (UTC), any month from January 2000 up to this one (picked, or typed as YYYY-MM where the browser has no month picker), Feature and Outcome, and page through 20, 50 or 100 lines at a time. Calls recorded before every AI feature was named read Other AI.

The ledger shows AI credits only. A refused request, which the AI never started, is not a call and is not listed.

Export the ledger

Export CSV downloads the month you are looking at, with the filters you chose, as a CSV file: one row per call, oldest first, with the columns time_utc, feature, person, email, outcome and credits. credits is whole credits as the ledger shows them, under 1 for a call charged less than half a credit. A cell that would start with =, +, - or @ is made inert, so a spreadsheet opens it as text. On Team the button carries the Business badge and opens the upgrade prompt instead.

Who changed what

Every change on this page is recorded in the audit log: ai.policy_updated for the switches and the workspace budgets, ai.role_policy_updated for a role’s features, ai.person_budget_updated for a person’s own budget, ai.effort_settings_updated for the company’s effort (what it was and what it became), and ai.ledger_exported for each export.

What is not AI

Some features find things by rules, not by AI. They use no AI credits, and no switch, role or budget on this page affects them:

the Row-count check and its Row-count changes in Data quality;
Suggested relationships, found from the tables’ keys and names (Suggested relationships);
Needs attention on Home, which ranks fired alerts, anomalies, digests and data-quality issues by rules.

The browser extension

On Business and Enterprise, the same page sets up the DataSquares browser extension for the workspace: whether it is on, who may use it, what it offers on sites with no data set, and the sites it works beside, each with the dashboard or model its chat starts on. Every question from the extension passes the controls above, as a chat question does. See Ask AI beside any web app.

The API

The routes behind this page need a signed-in company administrator, in the workspace the session is in; an API key can’t use them.

Route	What it does
`GET /api/ai/policy`	The switches, each role’s AI features, and the budgets with this month’s use
`PUT /api/ai/policy`	Set `aiEnabled`, `surfacesOff`, `workspaceMonthlyCredits` and `personMonthlyCredits`
`PUT /api/ai/policy/roles/{roleId}`	Set a role’s features: `{ "surfaces": { "summaries": true } }` (every feature but `search`, which roles don’t decide)
`PUT /api/ai/policy/people/{userId}`	Set a person’s own budget (`monthlyCredits`), or remove it with `null`
`GET /api/ai/ledger`	A month of AI calls: `month` (`YYYY-MM` from `2000-01` to `2999-12`, this month when left out; another value is `400`, and a month with no AI calls, a later one included, lists none), `surface`, `outcome`, `userId`, `page`, `pageSize`
`GET /api/ai/ledger/export`	The month as CSV; on Team, `403 PLAN_TIER_REQUIRED` with `details.feature` `ai_ledger_export`
`GET /api/ai/effort-settings`	The company’s effort: `defaultLevel`, `pickerShown`, `viewerLevel`, `viewersBoughtCredits`, `maxLevel` (`null` for a default), with the plan’s default level, the levels these settings start conversations at, never above the highest level (`effectiveDefaultLevel` for members in a workspace with no Answer depth of its own, `effectiveViewerLevel` for viewers), and whether viewers may run above Quick
`PUT /api/ai/effort-settings`	Set all five; a level above `maxLevel` is `400`, and a `viewerLevel` above `quick` on Team is `403 PLAN_TIER_REQUIRED` with `details.feature` `viewer_ai_levels`

AI credits: what AI uses, allowances, packs and auto top-up.
Users, roles & invites: roles and their permissions, AI Chat included.
Ask AI on a share: Ask AI for viewers of shared links and embeds.
Ask AI beside any web app: the browser extension, and setting it up.
Workspace settings & operations: the rest of the workspace’s settings.