Insights

An insight turns Hailer data into a SQL-queryable result. Data sources (activities from workflows, or datasets) are loaded into temporary SQLite tables, and a SQL query shapes the output. The result can be read over the API or exposed through a public link for use outside Hailer.

How an insight is built

An insight has two parts:

• Sources - one or more tables, each with a SQL name and columns mapped to workflow fieldIds (or activity metadata). Each source becomes a temporary SQLite table. Columns map by fieldId, so renaming a field or workflow does not break the insight.
• Query - a SQLite query over those tables that produces the result rows.

Authoring an insight

Insights are authored in the Hailer UI or as code with @hailer/sdk:

• Hailer UI - the insight editor previews the query result as sources and the SQL are edited.
• @hailer/sdk - define insights in insights.ts and push them to a workspace.

The API also provides v3.insight.create, v3.insight.update, and v3.insight.preview for authoring programmatically.

Reading the data

v3.insight.data executes a saved insight's query and returns { headers, rows, time }:

const result = await client.request("v3.insight.data", [insightId]);
console.table(result.rows);

Results are cached briefly for performance; pass { update: true } as the second argument to bypass the cache and get live data.

Public access

Every insight gets a 32-character publicKey at creation. Setting the insight to public (in the UI or via v3.insight.update) makes it reachable through that key without authentication.

CSV over HTTP - a GET request:

https://api.hailer.com/public/insight/<publicKey>

Parameter	Default	Purpose
type	csv	Output format: csv, tsv, or json.
delimiter	;	Field delimiter: ;, |, or ,.
separator	.	Decimal separator: . or , (must differ from the delimiter).
bom	(off)	Include a UTF-8 byte-order mark (set ?bom).

The URL can be used as a live data source, for example =IMPORTDATA("https://api.hailer.com/public/insight/<publicKey>") in Google Sheets, or as a source in Power BI or Excel.

JSON over RPC - v3.insight.public returns the same result by publicKey:

const data = await client.request("v3.insight.public", ["<publicKey>"]);

Anyone with the public key can read the insight's output. Setting public to false disables external access; the key itself is unchanged, so re-enabling public restores existing links.

Managing insights

• v3.insight.list - insights in a workspace the user can access.
• v3.insight.copy - duplicate an insight (assigns a new publicKey).
• v3.insight.member.add / v3.insight.member.remove - manage in-workspace access.
• v3.insight.remove - delete an insight.

Creating and editing insights is available to workspace administrators and owners.

Related

• Reference: insight - every insight endpoint with parameters and returns.
• @hailer/sdk insights - author insights as code.
• Permissions - who can create and read insights.