Guides

Adding your data

A new workspace is empty. Until it has data, questions return 422. Add a file, or connect a database, and wait for the schema to be ready.

Upload a CSV or Excel file

Upload in the app under Connect data, or with the API using the same key. Each sheet becomes a table, named after the file or sheet.

curl -X POST "https://api.factql.ai/clients/$CLIENT_ID/workspaces/$WORKSPACE_ID/files" \
  -H "X-API-Key: $FACTQL_API_KEY" \
  -F "file=@orders_2026.csv"

Files up to 50 MB, in .csv or .xlsx.
Uploading a file with the same name replaces its tables with the new version.
A workspace holds either files or a database connection, not both.

Connect a database

In the app, open Connect data and choose PostgreSQL or MySQL. FactQL tests the connection, then reads your tables.

Use a read-only database user. FactQL only runs SELECT statements, and a read-only user makes sure of it.

Wait until it's ready

FactQL reads the tables, then describes what each column means. Ask once status is ready.

curl "https://api.factql.ai/clients/$CLIENT_ID/schema/status?workspace_id=$WORKSPACE_ID" \
  -H "X-API-Key: $FACTQL_API_KEY"

Better answers

Clear column names help: order_total beats col7.
One row per record, with headers in the first row, works best for files.
Dates in a consistent format let questions like “last month” work.