canonical: https://jentic.com/apis/count.co/count

# Count Public API

The Count Public API lets developers and AI agents interact with a Count workspace programmatically, exposing canvases, catalogs, connections, projects, queries, and workspace members across 17 endpoints. Agents can run SQL queries against connected data sources, list and inspect canvases, refresh connection metadata or schemas, and export query results to CSV. The API is designed around the data canvas model rather than dashboards, so it suits exploratory analytics, automated reporting, and pipelines that need to read or trigger query jobs in Count.

## For AI agents

Run SQL queries, list canvases and catalogs, refresh data connections, and export results from a Count workspace. Suitable for automated reporting and exploratory analytics workflows.

## Scope

Does not handle data warehousing, ETL transformations, or dashboard rendering - use for SQL execution and canvas/connection management in a Count workspace only.

## Capabilities

- Run a SQL query against a connected warehouse and retrieve the resulting job key
- List canvases in a workspace and fetch a specific canvas by key
- Browse catalogs of curated tables and connections
- Refresh schema and metadata for a connected data source
- Export query results as a downloadable CSV file
- Search workspace content and list workspace members
- Create an agent on a canvas to automate analysis tasks

## Use cases

### Automated SQL Reporting

Trigger SQL queries in Count programmatically and pull the results into downstream pipelines or scheduled reports. The API accepts a query, returns a job key, and exposes a CSV export endpoint so the same query can feed a BI dashboard, an email digest, or a data warehouse load. Suitable for teams that already model data in Count and want to reuse those queries outside the canvas UI.

Example prompt: Submit a SQL query to POST `/v1/queries`, poll GET `/v1/queries/{job_key}` until complete, then call POST `/v1/queries/{job_key}/create_csv` to obtain the CSV file

### Canvas and Catalog Inventory

Build an inventory of every canvas, catalog, and connection in a Count workspace for governance or documentation purposes. The API exposes paginated list endpoints for canvases, catalogs, projects, and connections, and a workspace search endpoint for cross-resource lookup. Useful when migrating between BI tools or producing a catalogue of analytical assets.

Example prompt: Call GET `/v1/canvases`, GET `/v1/catalogs`, GET `/v1/projects`, and GET `/v1/connections` and produce a JSON manifest of every asset keyed by resource type

### Connection Health Monitoring

Keep Count connections in sync with upstream warehouses by refreshing metadata and schemas on a schedule. The API exposes refresh_metadata and refresh_schema endpoints per connection, so an agent can detect when a connected source has changed and trigger a refresh before users open the canvas. Reduces stale-schema errors during analyst sessions.

Example prompt: List all connections via GET `/v1/connections` then call POST `/v1/connections/{connection_key}/refresh_schema` for each connection that has not been refreshed in the last 24 hours

### AI Agent Analytics Workflow

Let an AI agent answer business questions by running SQL against a Count workspace through Jentic. The agent searches for the right operation in plain English, loads the schema, runs a query, and returns either the job key or the CSV. Because credentials live in your Jentic One instance, the agent never sees the raw bearer token. End-to-end integration takes under an hour rather than several days.

Example prompt: Use Jentic to search for 'run a query in Count', load the operation schema for POST `/v1/queries`, execute it with a user-supplied SQL string, and return the job_key

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/queries` | Run a SQL query and obtain a job key |
| GET | `/v1/queries/:job_key` | Get the status and result of a query job |
| POST | `/v1/queries/:job_key/create_csv` | Create a CSV file from a completed query |
| GET | `/v1/canvases` | List canvases in the workspace |
| GET | `/v1/connections` | List data connections |
| POST | `/v1/connections/:connection_key/refresh_schema` | Refresh the schema for a connection |
| GET | `/v1/workspaces/search` | Search across workspace content |

## Key resources

- **Canvases** — List, retrieve, and create agents on data canvases
- **Catalogs** — List and retrieve curated data catalogs
- **Connections** — List, retrieve, and refresh metadata or schema for data connections
- **Projects** — List and retrieve workspace projects
- **Queries** — Run SQL queries, retrieve job status, and create CSV exports
- **Workspaces** — List members and search across workspace content

## Why Jentic

- **Setup:** Wiring the Count Public API by hand means learning its bearer auth, pinning the api.app.count.co v1 host, and coding your own poll loop against the async query job flow. Through Jentic you install once, import the Count API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Count puts the job and connection keys in the URL path (`/v1/queries`/:job_key, `/v1/connections`/:connection_key/refresh_schema), so a rule can pin your agent to one query job or connection: it acts only on that resource. You choose the operations it may call, so changes like refreshing a connection schema are not included unless you add them.
- **Credential handling:** Your Count token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a SQL query' or 'export results to CSV', and Jentic returns the matching Count operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Metabase API** — Open-source BI platform with similar SQL-question and dashboard primitives
- **Tableau API** — Enterprise BI with workbooks, data sources, and embedded analytics
- **Snowflake API** — Cloud data warehouse that often sits behind a Count connection
- **dbt Cloud API** — Transformation layer that produces the modelled tables Count queries against

## FAQ

### What authentication does the Count Public API use?

The Count Public API uses HTTP bearer authentication. You generate a workspace API key in Count and pass it as `Authorization: Bearer <key>` on every request. When called through Jentic, the key is stored in your encrypted Jentic One instance and the agent receives a scoped session token rather than the raw key.

### Can I run arbitrary SQL with the Count Public API?

Yes. POST `/v1/queries` accepts a SQL string and runs it against the workspace's connected warehouse, returning a job key you can poll with GET `/v1/queries/{job_key}` until the job finishes. The result can then be exported as CSV via POST `/v1/queries/{job_key}/create_csv.`

### What are the rate limits for the Count Public API?

Count does not publish hard rate limits in the OpenAPI spec, but workspace plans determine concurrent query and connection refresh quotas. Treat it as best practice to keep query polling intervals at 2-5 seconds and avoid more than a handful of concurrent refresh_schema calls.

### How do I export a Count query as CSV through Jentic?

Search Jentic for 'export count query as csv', load the schema for POST `/v1/queries/{job_key}/create_csv`, then execute it with the job_key returned by your earlier query. Jentic handles the bearer credential and returns the CSV download URL.

### Does the Count Public API support webhooks or events?

No. The current spec only exposes synchronous REST operations across canvases, catalogs, connections, projects, queries, and workspaces. To detect query completion you poll GET `/v1/queries/{job_key}.`

### Can agents create new canvases via the Count Public API?

The spec does not include a create-canvas endpoint, but it does expose POST `/v1/canvases/agent` which creates an agent on a canvas. For full canvas authoring, use the Count UI.

### Can I limit what my agent is allowed to do with the Count Public API?

Yes. Because you run Jentic One yourself, your own rules decide which Count operations the agent may call and which token it may use, so you can allow read-only calls like GET `/v1/canvases` and POST `/v1/queries` while withholding write actions such as POST `/v1/connections/{connection_key}/refresh_schema.` Count also puts the job and connection keys in the URL path, so a rule can pin the agent to a single query job or one connection and nothing else. The token is stored in your own instance and injected only for the operations you have permitted.