Saylent

Export and API

Take your data out. Answers, citations, the engines' own searches, sources, off-site opportunities, share of voice, fixes and AI crawler counts as CSV or JSON, from the CLI, the MCP server, the app, or a read-only API.

Your runs are yours. Every surface exports the same tables, built by one function from the run bundle, so a column means the same thing wherever you download it:

WhereHow
CLInpx saylent export <run.json>: one CSV per table, or --format json
MCPthe export tool (inline rows or files), see the MCP server
AppExport on a run's report, and Export history on a brand's page
APIGET /api/v1/... with a personal API token, below

Everything is a count read from the runs or the crawler report. Nothing is estimated, scored or modelled on the way out.

From the CLI

npx saylent export ./acme.com/2026-11-02/run.json            # ./saylent-export/<table>.csv
npx saylent export ./acme.com --format json --out ./exports  # every dated run, one export.json
npx saylent export run.json --table opportunities --stdout   # one table to stdout
npx saylent crawlers access.log --out ./crawlers
npx saylent export run.json --crawlers ./crawlers/crawlers.json

A folder is read as one run when it holds a run.json, or as a brand's history when it holds <YYYY-MM-DD>/run.json folders (the layout saylent audit writes). Several runs export as one set of tables, with run_id and run_date on every row. It costs $0 and reads files only.

FlagWhat it does
--format <csv|json>csv (default) writes one <table>.csv per table; json writes export.json
--out <dir>Where to write. Default ./saylent-export
--table <name>Only this table
--crawlers <file>Add a crawlers.json from saylent crawlers --out
--stdoutPrint instead of writing. CSV needs --table

CSV follows RFC 4180 (CRLF line ends, quoted fields). A list cell, such as citation_urls, is joined with |; in JSON it stays an array. An empty CSV cell is a null: not recorded, or not applicable.

The tables (saylent.export/v1)

The format is versioned. A column added at the end of a table, or a table added at the end of the list, keeps the version; a renamed, removed or reordered column or table bumps it, and the JSON carries export_format and schema_version so a script can check.

Added within v1:

SinceChange
0.2.0answers.search_queries (the last column) and the search_queries table: the web searches each engine reported running
0.2.0The ai_referrals table: visits AI assistants sent, from a crawlers.json made by 0.2.0 or later

runs

One row per run.

ColumnMeaning
run_idThe run's id
run_dateWhen it finished (ISO 8601)
kindaudit or verify
profilesmoke or full
brandThe brand name
domainThe brand's domain
enginesThe engines and answer surfaces asked
modelsrole=model per role the run recorded
judge_modecross-family or single-family
questionsQuestions in the frozen set
answersAnswer rows, every engine and question
scored_answersAnswers that were judged and counted
recommendedScored answers that recommended the brand
mentionedScored answers that mentioned it
est_cost_usdThe run's recorded cost
baseline_run_idFor a verify, the run it re-asked

answers

One row per question and engine.

ColumnMeaning
run_id, run_dateThe run
qidThe question's id, the handle every receipt uses
qtypeThe question's type (category, comparison, branded, ...)
questionThe question as asked
engineEngine or surface id, such as chatgpt or google_ai_overview
engine_labelIts display name
statusok, not_shown (a surface showed no AI answer) or failed
brand_presentWhether the answer names the brand
mention_typerecommended, listed, compared, neutral, dismissed or absent
prominencefirst, early, buried or none
sentimentpositive, neutral or negative
rivals_namedRivals the answer named
citationsHow many pages it cited
citation_urlsThe cited URLs, in answer order
samplesDraws recorded for this answer
excerptThe judge's quoted excerpt
answer_textThe full answer text, verbatim
search_queriesThe web searches the engine ran for this answer, in order (the same draw as answer_text). An empty list: the engine reports its searches and ran none. Null (an empty CSV cell): the engine does not report them, or the run predates 0.2.0

citations

One row per cited URL.

ColumnMeaning
run_id, run_dateThe run
qid, engineThe answer that cited it
positionIts position in the answer's citations, from 0
urlThe URL as cited
hostThe source domain (archive and redirect wrappers unwrapped)
page_titleThe page's title, when the run read it
page_typeThe page's type, when read (listicle, review, docs, ...)
brand_on_pageWhether the brand is on the page; empty when not read
rivals_on_pageRivals found on the page

sources

One row per cited domain, most cited first. The same numbers as Sources & opportunities.

ColumnMeaning
run_id, run_dateThe run
hostThe domain
typeIts type, such as review_site or editorial
type_ruleThe rule that set the type
citationsCitation rows for it
shareIts share of every citation in the run, 0 to 1
answersDistinct answers citing it
brand_named_answersOf those, answers that name the brand
rival_won_answersOf those, answers that name a rival and not the brand
enginesEngines that cited it

opportunities

One row per off-site opportunity: a domain cited in answers that name a rival and not you, where you were not found on any page read.

ColumnMeaning
run_id, run_dateThe run
rankIts rank, 1 first
host, typeThe domain and its type
evidenceRival-won, non-branded answers citing it
enginesEngines behind those answers
rivalsRivals those answers named, most often first
page_checkrivals_on_page, brand_missing or unread
brand_named_answersAnswers citing it that do name the brand (context)
top_page_urlThe most cited page on it, the one to pitch first
whyThe one-line reason, as the report prints it
receiptsThe answers behind it, as qid:engine

share_of_voice

Who the answers name. One row per name with scope all, then one per engine that named it. It counts answers, not market share.

ColumnMeaning
run_id, run_dateThe run
nameThe brand or rival
is_brandtrue for your brand
scopeall, or an engine id
namedAnswers naming it in that scope
recommendedAnswers recommending it (your brand, scope all only)
receiptsThe answers, as qid:engine

fixes

One row per drafted fix, in the report's order. The drafted text itself is in the run bundle and in saylent fixes <run.json> --fix <key>.

ColumnMeaning
run_id, run_dateThe run
rankIts rank, 1 first
fix_keyIts id, used by saylent fixes apply --only
titleThe fix
factorThe diagnosis rule that raised it
weightIts evidence weight
effortS, M or L
enginesEngines it concerns
evidenceThe evidence lines the diagnosis recorded
has_artifactWhether a paste-ready draft exists

crawlers

One row per bot, from a crawlers.json passed with --crawlers. Empty otherwise. The same numbers as AI crawlers.

ColumnMeaning
window_from, window_toThe log window
bot_id, botThe bot's id and name
operatorWho runs it
purposetraining, search, user or another purpose
aiWhether it is an AI crawler
requestsRequests in the window
pagesDistinct pages fetched
blocked401, 403, 429 and firewall blocks
server_errors5xx responses
not_found404 and 410 responses
verified, unverifiedIP-verified requests; empty without --verify-ips
first_seen, last_seenFirst and last request

search_queries

Query fan-out: one row per web search an engine ran before answering, per draw, verbatim from the provider's response. Only ChatGPT, Claude and Gemini report theirs; Perplexity's API and the SerpApi surfaces do not, so they add no rows. Runs recorded before 0.2.0 add none either. Reading these fields costs nothing extra: they are in the responses a run already pays for.

ColumnMeaning
run_id, run_dateThe run
qidThe question
enginechatgpt, claude or gemini
sampleThe draw, 0 first; a question asked once is draw 0
positionThe search's place in that draw, 1 first
queryThe query text, as the engine sent it

ai_referrals

Visits from people that AI assistants sent, from the same crawlers.json as crawlers (empty without one, and for a file made before 0.2.0). One row per assistant, from the list on AI crawlers. A floor, not a total: a visit with no Referer and no utm_source looks like direct traffic.

ColumnMeaning
window_from, window_toThe log window
assistant_id, assistantThe assistant's id and name, such as chatgpt and ChatGPT
operatorWho runs it
visitsRequests from a browser (no known bot user agent) that it sent
via_referrerOf those, matched by the Referer header's host
via_utm_sourceMatched by utm_source instead (no matching Referer)
top_pagesLanding pages with their visits, most first (up to 10)
first_seen, last_seenFirst and last visit

In the app

A finished run's report has an Export menu: each table as CSV, everything as JSON, and the lossless run bundle (run.json) that saylent report, saylent verify and saylent export read. A brand's page has Export history: the same tables across its last 24 finished runs, plus crawlers and ai_referrals from its newest uploaded log. Every download runs as you, so you only ever get your own runs.

Read-only API

The self-hosted app serves the same data over HTTP for your own scripts, dashboards and agents. It is read-only: nothing it does can start a run, spend credits or change a row.

Tokens

Create a token under Settings › API tokens. It is shown once; Saylent keeps only its SHA-256 hash. A token reads exactly what its owner can read in the app, and revoking it takes effect on the next request. Requires migration 0048_api_tokens.sql.

export SAYLENT_TOKEN=slt_...
curl -H "Authorization: Bearer $SAYLENT_TOKEN" https://your-app.example/api/v1/brands

A signed-in browser session works too, so a link opened in the app downloads directly.

Endpoints

Method and pathReturns
GET /api/v1/brandsYour brands: id, name, domain, created_at
GET /api/v1/brands/{id}/runsThe brand's finished runs, newest first, with their counts
GET /api/v1/runs/{id}One run as the saylent.export/v1 document
GET /api/v1/runs/{id}?format=csv&table=answersOne table of one run as CSV
GET /api/v1/runs/{id}?format=bundleThe lossless run bundle (run.json)
GET /api/v1/brands/{id}/exportThe brand's last 24 finished runs as one export (format=csv&table= too)
GET /api/v1/openapi.jsonThis API as an OpenAPI 3.1 document (no token needed)

The same OpenAPI document is published with these docs: saylent-api-v1.json, ready for an API client or an agent that reads OpenAPI.

/api/v1/runs/{id} also takes table= with JSON, to return one table.

Limits and errors

Each token owner gets 60 requests a minute, counted across tokens; the 61st gets 429 with a Retry-After header. Errors are JSON, {"error": "..."}: 401 for a missing, unknown or revoked token, 404 for a run or brand that is not yours or does not exist (the two look the same on purpose), 409 for a run that has not finished, 400 for an unknown format or table, and 503 when the deployment cannot check tokens (for example, no service-role key). Responses carry Cache-Control: no-store.

On this page