` | Override the map title in the destination. | | `--skip-source-validation` | Skip validating that destination connections can read source tables/queries. | | `--keep-privacy` | Preserve privacy setting from source (default: true). | For a full walkthrough including connection-mapping scenarios and troubleshooting, see [Examples → Copying maps and workflows between organizations](/carto-for-agents/cli/examples#copying-maps-and-workflows-between-organizations). ## `carto maps screenshot` {% hint style="info" %} `carto maps screenshot` is **experimental**. Its flags, render engines, and output may change in future releases. {% endhint %} Render a PNG of the map. Two render engines: * **`light`** (default) — a bundled minimal viewer (`@deck.gl/carto` `fetchMap`). \~2.5 MB asset, \~8 s cold start, \~10 MB network. Renders layers + basemap. **No widgets, legends, popups, or chrome.** * **`full`** — the full CARTO Builder viewer at `/viewer/:mapId` rendered in a headless iframe. \~20 s, \~28 MB. Full feature parity. ```bash carto maps screenshot abc123 -o map.png carto maps screenshot abc123 --lat 40.42 --lng -3.70 --zoom 12 --hide-overlays carto maps screenshot abc123 --render-engine full ``` | Option | Description | | -------------------------------------------------- | ----------------------------------------------------- | | `--render-engine <e>` | `light` (default) or `full`. | | `-o, --output <path>` | Output file path (default: `screenshot.png`). | | `--width <px>` / `--height <px>` | Viewport size (default: 1280 × 800). | | `--lat <deg>` / `--lng <deg>` | Center coordinates. | | `--zoom <n>` / `--bearing <deg>` / `--pitch <deg>` | Viewport. | | `--layers <indices>` | Comma-separated visible layer indices (e.g. `"0,2"`). | | `--search <query>` | Address or `"lat,lng"` to center on. | | `--hide-overlays` | Hide CARTO logo, attribution, zoom controls, legend. | | `--wait <seconds>` | Optional pad after auto-detected render (default: 0). | | `--timeout <seconds>` | Navigation/render timeout (default: 60). | | `--full-page` | Capture full scrollable page instead of viewport. | | `--no-cache` | Bypass persistent Chromium profile (`full` engine). | {% hint style="info" %} **Optional Playwright install.** `maps screenshot` launches a headless Chromium. The browser is an opt-in dependency to keep the CLI install small: ```bash npm install playwright-core npx playwright install chromium # ~300 MB ``` The screenshot authenticates as the current CLI user, so it works on private, shared, and public maps you have access to. {% endhint %} ## `carto maps delete` ```bash carto maps delete <map-id> carto maps delete <map-id> --yes # Skip confirmation ``` ## Examples ```bash # Create from a bundle file carto maps create < map.json # Round-trip: get → edit → update carto maps get abc123 --json > /tmp/map.json jq '.title = "Q3 Dashboard"' /tmp/map.json | carto maps update abc123 # Validate locally (no network), then create carto maps validate < map.json && carto maps create < map.json # Update + publish in one go carto maps update abc123 < shared.json --publish # Agent introspection carto maps agents status carto maps schema layer.h3 ``` # workflows Manage CARTO Workflows — list, inspect, create, update, copy, validate, verify-remote, run, share, schedule, publish as MCP tools, and install extensions. ```bash carto workflows list [options] # List workflows carto workflows get <id> # Pretty details; --json = round-trippable bundle carto workflows create [--file <bundle.json>] # Create from a bundle carto workflows update <id> [--file <bundle.json>] # Update (partial bundles OK) carto workflows delete <id> # Delete workflow carto workflows copy <id> --dest-profile <name> # Duplicate (cross-tenant or same-tenant) carto workflows schema [section] # JSON Schema reference for agents carto workflows validate [--file <bundle.json>] # Tier-0 offline (Zod-only) bundle check carto workflows verify-remote <id|--file …> --connection <c> # Tier-0 + Tier-2 deep validation against a warehouse carto workflows to-sql [--file <bundle.json>] # Compile bundle → SQL preview (what `run` would submit) carto workflows components list # Agent-facing component catalog carto workflows components get <names> # Full input/output signature for components carto workflows run <id> # Execute workflow; returns per-node outputs carto workflows run output <id> <node-id> # Fetch a node's output rows carto workflows run status <job-id> # Poll an async-submitted run carto workflows share <id> [--org | --with <email>] # Share workflow carto workflows unshare <id> # Revert to private carto workflows mcp publish|unpublish|describe|list # MCP tool lifecycle carto workflows schedule add|update|remove <id> # Warehouse cron lifecycle carto workflows extensions install --file <ext.zip> --connection <name> # Install an extension zip ``` ## The bundle model `workflows get <id> --json` returns a **round-trippable bundle** (title and description lifted, server fields stripped, privacy synthesised). Pipe straight back into `workflows create --file` or `workflows update --file`: ```bash carto workflows get abc123 --json > /tmp/wf.json jq '.title = "New title"' /tmp/wf.json | carto workflows update abc123 --file - ``` Structural validation runs on Zod schemas under `src/schemas/workflows/`. For the full bundle recipe, see the [`carto-create-workflow`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-workflow) skill. {% hint style="info" %} **GeoJSON inputs**: `native.tablefromgeojson` and `native.drawcustomgeographies` accept both a stringified `FeatureCollection` and a `FeatureCollection` object on the input `value` field, so workflows that ingest GeoJSON can be authored from the CLI. {% endhint %} ## `carto workflows list` | Option | Description | | -------------------------------- | -------------------------------------------------------------------------------------- | | `--page <n>` / `--page-size <n>` | Pagination. | | `--order-by <field>` | `updated_at` (default), `created_at`, `title`. Aliases `updated` / `created` accepted. | | `--order-direction <dir>` | `ASC` or `DESC`. | | `--search <term>` | Search filter. | | `--privacy <level>` | Filter by privacy: `public` or `shared`. | | `--tags <json>` | Filter by tags (JSON array). | | `--all` | Fetch all pages automatically. | ## `carto workflows create` / `carto workflows update` | Option | Description | | ------------------------------ | ----------------------------------------------------------------------------- | | `--file <path>` | Read bundle JSON from a file (or stdin via `-`). | | `--verify` | Run Tier-2 checks (sources region + SQL dry-run + engine compile) post-write. | | `--verify sources,sql,compile` | Subset — each can also be used alone. | ```bash # Create from a bundle carto workflows create --file my-pipeline.json # Update + verify post-write carto workflows update abc123 --file pipeline.json --verify ``` ## `carto workflows validate` / `carto workflows verify-remote` * **`validate`** — **Zod-only**, offline, no network. Use it to iterate on a bundle locally before writing. The `--connection` and `--no-engine` flags are removed; for warehouse-aware validation use `verify-remote`. * **`verify-remote`** — Standalone command, hard-errors without a connection. Runs the full Tier-0/1/2 stack (structural + engine compile + schema trace + sources + customsql) without writing the workflow. Useful before opening a PR that ships a new bundle. Advisory warnings appear in the output but no longer fail the exit code; pass `--strict` to restore the previous behaviour, where any warning fails the run. ```bash # Offline structural check carto workflows validate --file bundle.json # Full warehouse-side check carto workflows verify-remote --file bundle.json --connection carto_dw # Same, but fail on advisory warnings (CI gates) carto workflows verify-remote --file bundle.json --connection carto_dw --strict ``` | Option | Description | | --------------------------- | -------------------------------------------------------------------------------------- | | `--file <path>` | Bundle JSON path (or pipe via stdin). | | `--connection <name\|uuid>` | (Required for `verify-remote`) Override `bundle.connectionId`. | | `--mode <create\|update>` | (`validate` only) Validation mode (default: `update`). | | `--strict` | (`verify-remote` only) Fail the exit code on any advisory warning, not just on errors. | ## `carto workflows to-sql` Compile a bundle to the SQL that `run` would submit, without executing: ```bash carto workflows to-sql --file bundle.json ``` ## `carto workflows components` Agent-facing component catalog. Use `list` to discover components, `get` to fetch their full input/output signatures. ```bash # Browse native components carto workflows components list --connection carto_dw --group Joins # Full signatures (for agent composition) carto workflows components get native.customsql,native.joinv2 --connection carto_dw --json # Include input-format reference entries carto workflows components get native.customsql --connection carto_dw --input-formats ``` | Option | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `--connection <name\|uuid>` | (Required) Catalog is fetched per-connection so extensions and stored procedures appear alongside native components. Provider is inferred. | | `--group <name>` | Filter `list` to a specific group (e.g. `Joins`). | | `--search <term>` | Substring match across name / title / description. | | `--starred` | Only starred components. | | `--include-deprecated` | Include deprecated components (hidden by default). | | `--input-formats` | (`get` only) Include deduped format reference entries for all input/output types. | {% hint style="warning" %} **Breaking in 0.7:** `components list` and `components get` now require `--connection`. The previous `--provider` flag was removed; the provider is now inferred from the connection so extensions and stored procedures appear in the catalog. Extension and stored-procedure load failures surface as warnings (in JSON output under a `warnings` array; in text as `Warning: …` lines). {% endhint %} For `Selection`-typed inputs (e.g. `native.isolines.mode`) the JSON output includes both `options` (the wire values the engine accepts, e.g. `"walk"`) and `optionsText` (the matching human-readable labels, e.g. `"Walk"`). Use `options` when populating the bundle. ## `carto workflows run` Execute a workflow and fetch results: ```bash carto workflows run <id> # Run synchronously; returns per-node outputs carto workflows run <id> --async # Return immediately with a job ID carto workflows run status <job-id> # Poll the async job carto workflows run output <id> <node-id> # Fetch a specific node's output rows ``` ## `carto workflows share` / `carto workflows unshare` Identify users by email with `--with`. The CLI resolves each email to a user ID, so a typo fails loudly rather than sharing with the wrong person. ```bash # Share with the whole organization carto workflows share <id> --org # Share with a specific user by email carto workflows share <id> --with someone@example.com # Repeat or comma-separate to reach several people at once carto workflows share <id> --with a@example.com --with b@example.com carto workflows share <id> --with a@example.com,b@example.com # Also grant edit access, and see who has access today carto workflows share <id> --with someone@example.com --can-edit carto workflows share <id> --list # Remove one person's access, or revert to private carto workflows unshare <id> --with someone@example.com carto workflows unshare <id> ``` **Options:** | Option | Description | | ---------------- | ---------------------------------------------------------------------- | | `--org` | Share with the entire organization (`unshare` drops org-wide sharing). | | `--with <email>` | Share with a user by email. Repeatable, or comma-separated. | | `--can-edit` | Grant edit access as well as read (`share` only). | | `--list` | Show the current sharing state without changing it (`share` only). | {% hint style="info" %} `--user-id` and `--user-email` were removed in v0.10.0. Use `--with <email>`. {% endhint %} ## `carto workflows mcp` Publish a workflow as an MCP tool so it shows up in the CARTO MCP Server: ```bash carto workflows mcp publish <id> [options] # Expose this workflow as an MCP tool carto workflows mcp unpublish <id> # Remove from MCP catalog carto workflows mcp describe <id> # Show current MCP tool registration carto workflows mcp list # List all workflows published as MCP tools ``` Workflows on Redshift and Oracle connections always publish as Async tools. A publish that requests Sync execution on these connections is rejected with an error explaining why. See the [Workflows as MCP Tools](/carto-user-manual/workflows/workflows-as-mcp-tools) guide for the publishing flow end-to-end. ## `carto workflows schedule` Warehouse-side cron lifecycle for the workflow's run schedule: ```bash carto workflows schedule add <id> --cron "0 6 * * *" carto workflows schedule update <id> --cron "0 6 * * 1-5" carto workflows schedule remove <id> ``` ## `carto workflows copy` Duplicate a workflow between profiles. Connection mapping behaves like `maps copy`. ```bash # Auto-map by name carto workflows copy abc123 --dest-profile production # Explicit connection carto workflows copy abc123 \ --source-profile staging \ --dest-profile production \ --connection prod-bigquery ``` | Option | Description | | ---------------------------- | ----------------------------------------------------------- | | `--dest-profile <name>` | (Required) Destination profile name. | | `--source-profile <name>` | Source profile (default: current). | | `--connection <name>` | Destination connection name (auto-maps by name if omitted). | | `--connection-mapping <map>` | Per-source map: `"src1=dst1,src2=dst2"`. | | `--title <title>` | Override workflow title in the destination. | | `--skip-source-validation` | Skip validating source table accessibility. | For the full walkthrough including connection-mapping scenarios, see [Examples → Copying maps and workflows between organizations](/carto-for-agents/cli/examples#copying-maps-and-workflows-between-organizations). ## `carto workflows extensions install` Install a CARTO Workflows extension zip (bundles `metadata.json` + provider-specific SQL) into a warehouse connection. ```bash carto workflows extensions install --file my-extension.zip --connection carto_dw ``` | Option | Description | | --------------------- | ------------------------------------------------------------------------- | | `--file <path>` | (Required) Path to the extension `.zip`. | | `--connection <name>` | (Required) Connection to install into. Provider must match the extension. | ## Examples ```bash # List ETL workflows, recently updated first carto workflows list --search "ETL" --order-by updated_at # Round-trip get → edit → update carto workflows get abc123 --json > /tmp/w.json jq '.title = "New title"' /tmp/w.json | carto workflows update abc123 --file - # Local validation before write carto workflows validate --file bundle.json # Full warehouse-side verification before merging a bundle PR carto workflows verify-remote --file bundle.json --connection carto_dw # Preview the SQL `run` would submit carto workflows to-sql --file bundle.json # Publish as MCP tool so agents can call it carto workflows mcp publish abc123 ``` # projects Manage CARTO projects — the containers that group maps and workflows. A project is a top-level folder; it can hold subfolders, native maps and workflows, and shortcuts to maps or workflows that live elsewhere. ```bash # Read carto projects list [options] # Top-level projects carto projects get <id|name> # Project details + full contents tree # Top-level CRUD carto projects create --name <name> # New top-level project carto projects rename <path> --to <name> # Rename a folder carto projects delete <path> # Delete a folder or shortcut # Asset placement carto projects add <path> --folder <name> # Create a subfolder inside a project carto projects add <path> --map <map-id> # Add an existing map (creates a shortcut) carto projects add <path> --workflow <wf-id> # Add an existing workflow (creates a shortcut) carto projects move <path> --to <path> # Move a folder or shortcut to a new parent # Local-sync workflow carto projects init <name> # New project + scaffold a local working dir carto projects clone <id|name> # Materialize an existing project to disk carto projects status # Show local-vs-clone diff (run inside a checkout) ``` ## Identifier resolution Project arguments accept **either** the UUID (e.g. `62c90ed4-eeec-46d0-bda9-c7ea173e26f0`) or the project name. Names are resolved via the entries search; ambiguous matches error out and ask for the UUID. Nested locations use **slash paths**: `Q2 Analytics/Maps/Drafts`. The first segment must be a top-level project (or its UUID); subsequent segments walk the tree by title-match within each parent folder. ## Adding maps and workflows: shortcuts under the hood The CARTO platform doesn't currently expose a way to move an existing map or workflow into a folder — assets live at the account root. The mechanism for making one appear inside a project is to create a **shortcut** (an alias entry pointing at the underlying asset). `carto projects add <path> --map <id>` creates that shortcut for you. The map itself is not moved; deleting the shortcut later only removes the alias, not the map. ## Local-sync workflow Treat a CARTO project as a working directory you can clone, edit, and sync: ```bash # Start a brand-new project — creates server-side and scaffolds a local dir carto projects init "Q2 Analytics" --color "#3478f6" cd q2-analytics $EDITOR AGENTS.md # capture project context for an agent # Or check out an existing project carto projects clone "Q2 Analytics" cd q2-analytics ls -R # AGENTS.md, README.md, *.map.json, *.workflow.json # See what's changed locally vs the clone carto projects status # Optionally check whether anything moved on the server since you cloned carto projects status --server ``` The clone lays down: * `.carto/project.json` — manifest with project ID, content hashes, server timestamps, and the recursive entry tree. * `AGENTS.md`, `README.md` — tracked scaffold docs (their hashes go in the manifest, so edits show up in `status`). * `.gitignore` — meta, untracked. * For each entry: a directory (folders) or a `*.map.json` / `*.workflow.json` bundle. Pushing edits back uses the existing per-resource verbs: ```bash $EDITOR my-map.map.json carto maps update <map-id> < my-map.map.json ``` ## Common flags **`projects list`** — `--in <id|name>`, `--search <query>`, `--owner <me|others>`, `--mine`, `--order-by <field>` (`updatedAt` / `title`), `--order-direction <ASC|DESC>`, `--page`, `--page-size`. **`projects get`** — `--depth <n>` (0 = unbounded, 1 = top level only), `--budget <n>` (folder-lookup cap, default 500), `--no-entries` (metadata only). **`projects create`** — `--name <name>`, `--color <hex>`, `--file <path>` (read full create payload from JSON). **`projects add`** — exactly one of `--folder <name>`, `--map <map-id>`, `--workflow <id>`, plus `--color <hex>` for new subfolders. **`projects rename`** — `--to <new-name>`. **`projects move`** — `--to <path>`. Top-level → top-level is not supported by the API today. **`projects delete`** — `--yes` to skip the confirmation prompt. **`projects init`** / **`projects clone`** — `--path <dir>` (default: `./<slug-of-name>/`), `--force` (write into a non-empty dir / overwrite scaffold). `clone` adds `--shallow` (skip bundle fetches, just structure) and `--budget <n>`. **`projects status`** — `--path <dir>` (project root, defaults to walking up from CWD), `--server` (also check for changes on the CARTO server since clone). ## Examples ```bash # Browse carto projects list --mine carto projects list --search analytics carto projects get "Q2 Analytics" carto projects get "Q2 Analytics/Maps" # Build out a project carto projects create --name "Q2 Analytics" --color "#3478f6" carto projects add "Q2 Analytics" --folder "Maps" carto projects add "Q2 Analytics/Maps" --map 62c90ed4-eeec-46d0-bda9-c7ea173e26f0 carto projects add "Q2 Analytics" --workflow b32f9fff-4303-4f75-bf7a-1f661c60b53a # Reorganize carto projects rename "Q2 Analytics/Maps" --to "Production maps" carto projects move "Q2 Analytics/Production maps" --to "Q1 Archive" # Clean up carto projects delete "Q2 Analytics" --yes ``` # connections Manage data warehouse connections (BigQuery, Snowflake, Redshift, PostgreSQL, Databricks, …). ## `carto connections list` List all connections. ```bash carto connections list ``` ## `carto connections get <connection-id>` Get details for a specific connection. The output includes a `Shared with:` line listing the organization, users and groups that can use it. ```bash carto connections get conn_xyz789 ``` ## `carto connections create <json-body>` Create a new connection. The body's shape depends on the provider. ```bash carto connections create '{ "name": "my-snowflake", "type": "snowflake", "parameters": { "account": "myaccount", "warehouse": "compute_wh" } }' ``` ## `carto connections update <connection-id> <json-body>` Update a connection. ```bash carto connections update conn_xyz789 '{ "parameters": { "warehouse": "new_wh" } }' ``` ## `carto connections delete <connection-id>` Delete a connection. ```bash carto connections delete conn_xyz789 ``` ## `carto connections share` / `carto connections unshare` Control who can use a connection: the whole organization, specific users, or groups. Identify users by email with `--with` and groups by name or id with `--group`. The CLI resolves both before changing anything, so a typo fails loudly instead of sharing with the wrong person. New grants are added to the access the connection already has; use `unshare` to take access back. The connection can be given by id or by name. ```bash # Share with the whole organization carto connections share my-conn --org # Share with specific users, and with a group carto connections share my-conn --with a@example.com,b@example.com --group Analysts # See who has access today, without changing anything carto connections share my-conn --list # Remove one person's access, or revert to owner-only carto connections unshare my-conn --with a@example.com carto connections unshare my-conn ``` **Options:** | Option | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------ | | `--org` | Share with the entire organization (`unshare` drops organization-wide access and keeps specific users and groups). | | `--with <email>` | Share with a user by email. Repeatable, or comma-separated. | | `--group <name>` | Share with a group by its name or id. Repeatable, or comma-separated. | | `--list` | Show the current sharing state without changing it (`share` only). | People you share with use the connection under its owner's credentials, unless the connection requires viewer credentials. Organization Admins can turn connection sharing off for the whole organization, in which case `share` is refused. See [Sharing a connection](/carto-user-manual/connections/sharing-a-connection) in the user manual for how sharing behaves in CARTO. {% hint style="info" %} Sharing a connection with specific users or groups needs a CARTO platform that supports connection access policies. On an older Self-hosted deployment the command stops with an upgrade message before changing anything. {% endhint %} ## `carto connections browse <name> [path]` Browse the resource tree exposed by a connection (databases, schemas, tables, tilesets). Useful for picking source paths when authoring maps or workflows without leaving the terminal. ```bash # Top-level tree for a connection carto connections browse carto_dw # Drill into a specific subtree carto connections browse carto_dw "carto-demo-data" ``` **Options:** | Option | Description | | -------------------- | ---------------------------------------------------------- | | `--depth <n>` | Max tree depth to expand (default: server default). | | `--max-items <n>` | Max total items to return (default: server default of 30). | | `--max-children <n>` | Max children per node (default: server default). | ## `carto connections describe <name> <table-path>` Get the schema and details for a single table on a connection (column names, types, partitioning, row count when available). ```bash carto connections describe carto_dw "carto-demo-data.demo_tables.nyc_collisions" ``` ## `carto connections search <name> <query>` Free-text search across the tables and views reachable through a connection. ```bash carto connections search my-conn "customers" carto connections search my-conn "orders" --scope "mydb.public" --type table ``` **Options:** | Option | Description | | --------------- | ------------------------------------------------------ | | `--type <kind>` | Filter by resource type: `table` or `view`. | | `--limit <n>` | Max results, 1–100 (default: 20). | | `--scope <fqn>` | Narrow the search to a subtree (e.g. `"mydb.public"`). | # named-sources Manage **Named Sources** — server-side aliases for SQL queries. Instead of exposing raw SQL in client applications, create a Named Source with a name and reference it by name wherever the CARTO APIs accept a `sqlQuery` parameter. {% hint style="info" %} The Named Sources API requires **OAuth Access Tokens** (from `carto auth login`), not API Access Tokens. {% endhint %} ```bash carto named-sources list # List named sources carto named-sources get <name> # Get named source details carto named-sources create --name <n> --source <sql> # Create named source carto named-sources update <name> --source <sql> # Update named source carto named-sources delete <name> # Delete named source ``` ## `carto named-sources list` | Option | Description | | ------------------ | ----------------------------- | | `--page-size <n>` | Items per page (default: 10). | | `--page <n>` | Page number (default: 1). | | `--search <query>` | Search named sources by text. | ## `carto named-sources create` | Option | Description | | ---------------- | -------------------------------------------------------------------------------- | | `--name <name>` | Source name (3–50 chars, lowercase letters/numbers, dashes/underscores allowed). | | `--source <sql>` | SQL query for the named source. | ## Examples ```bash # List all named sources carto named-sources list # Search named sources carto named-sources list --search "my_source" # Create a named source carto named-sources create --name my_source --source "SELECT * FROM project.dataset.table" # Get details carto named-sources get my_source # Update the SQL query carto named-sources update my_source --source "SELECT id, geom FROM project.dataset.table" # Delete (with confirmation) carto named-sources delete my_source # Delete (skip confirmation for CI/CD) carto named-sources delete my_source --yes ``` # do (Data Observatory) Browse, search, and subscribe to datasets from the CARTO Data Observatory catalog (10,000+ spatial datasets from 50+ providers). ```bash # Discover available filters (countries, categories, providers, licenses, etc.) carto do filters # All filter values with dataset counts carto do filters --json | jq '.categories' # Just categories (programmatic) # Browse and search carto do list --category demographics # Browse datasets by category carto do list --country usa --limit 10 # Browse by country carto do list --provider experian # Browse by provider carto do list --license public # Filter by license type carto do search "demographics united states" # Full-text search carto do search "flood risk" --license public # Search with filters # AI-powered semantic variable search (requires embeddings) carto do search-variables "purchasing power" --country deu carto do search-variables "population density" --limit 10 # Dataset details carto do details <dataset-id> # Full dataset metadata carto do sample <dataset-id> # Data sample + data dictionary # Subscriptions (public datasets only — premium requires contacting sales) carto do subscriptions # List your subscriptions carto do subscribe <dataset-id> # Subscribe using catalog slug carto do subscribe wp_population_29d72d59 # Resolves slug → creates BQ view carto do subscribe <id> --filter "WHERE country_iso = 'US'" # Partial subscription carto do subscribe <id> --columns "geoid, population, geom" # Specific columns only carto do subscribe <id> --connection my-sf --destination db.tbl # Subscribe + transfer carto do unsubscribe <dataset-id> # Remove a subscription carto do unsubscribe <dataset-id> --yes # Skip confirmation ``` ## `carto do list` / `carto do search` | Option | Description | | -------------------- | ---------------------------------------------------------- | | `--category <name>` | Filter by category (e.g. `Demographics`, `Environmental`). | | `--provider <name>` | Filter by provider (e.g. `Experian`, `TomTom`). | | `--country <name>` | Filter by country. | | `--license <type>` | Filter: `premium` or `public`. | | `--limit <n>` | Results per page (default: 20). | | `--page <n>` | Page number (default: 1). | | `--order-by <field>` | Order: `popular`, `recent`, `alphabetical` (list only). | ## `carto do subscribe` | Option | Description | | ----------------------- | ---------------------------------------------------------------------- | | `--filter <where>` | SQL `WHERE` clause to filter data (e.g. `"WHERE country_iso = 'US'"`). | | `--columns <cols>` | Comma-separated columns to include (default: all). | | `--connection <name>` | Transfer data to this connection after subscribing. | | `--destination <table>` | Destination table (required with `--connection`). | # import Import a geospatial file into your data warehouse from a local file or URL. Waits for completion by default. **Supported formats:** CSV, GeoJSON, GeoPackage, GeoParquet, KML, KMZ, TAB, Shapefile (zip).\ **Size limit:** 5 GB per file.\ **Supported warehouses:** CARTO DW, BigQuery, Snowflake, PostgreSQL, Redshift, Databricks, Oracle. ```bash carto import --file <path> --connection <name> --destination <table> carto import --url <url> --connection <name> --destination <table> carto import status <jobId> # Fetch status of an async import job ``` An import that finished but lost rows ends with the status `completed_with_warnings`. The table exists and the CLI exits successfully, printing how many rows were dropped and why: rows without a readable location are in the table without geometry, rows with formatting errors were not imported. With `--json`, the counts are in `metadata.droppedRows`, `metadata.droppedRowReasons` and `metadata.droppedRowsByReason`. ## Options | Option | Description | | --------------------- | ------------------------------------------------------------------------ | | `--file <path>` | Local file to upload (mutually exclusive with `--url`). | | `--url <url>` | Remote file URL to import (mutually exclusive with `--file`). | | `--connection <name>` | (Required) Connection name. | | `--destination <fqn>` | (Required) Fully qualified table name. | | `--overwrite` | Overwrite an existing table (default: false). | | `--no-autoguessing` | Disable automatic column type detection (default: autoguessing enabled). | | `--async` | Return immediately with the job ID instead of polling to completion. | ## Examples ```bash # Import local CSV carto import --file ./data.csv --connection carto_dw --destination project.dataset.my_table # Import from URL with overwrite carto import \ --url https://example.com/data.geojson \ --connection carto_dw \ --destination project.dataset.table \ --overwrite # Kick off async, then poll status separately carto import --file ./big.csv --connection carto_dw --destination my.table --async carto import status <jobId> # JSON output (for scripts) carto import --file ./data.geojson --connection carto_dw --destination project.dataset.table --json ``` ## CSV auto-detection For CSV files, CARTO automatically detects geometry columns or builds geometries from lat/lon columns: * **Geometry columns:** `geom`, `Geom`, `geometry`, `the_geom`, `wkt`, `wkb`. * **Latitude columns:** `latitude`, `lat`, `Latitude`. * **Longitude columns:** `longitude`, `lon`, `Lon`, `Longitude`, `lng`, `Lng`. Disable with `--no-autoguessing` if you need full control over the schema. # export Export a warehouse table to a file. Returns a download URL (24 h expiry) or writes to cloud storage. **Formats:** `geoparquet`, `geojson`, `shapefile`, `csv`, `geopackage`, `kml`, `kmz`, `tab`. ```bash carto export --connection <name> --source <table> --format <fmt> carto export status <jobId> # Fetch status of an async export job ``` ## Options | Option | Description | | --------------------- | ---------------------------------------------------- | | `--connection <name>` | (Required) Connection name. | | `--source <fqn>` | (Required) Source table name. | | `--format <fmt>` | (Required) Output format. | | `--select <cols>` | Comma-separated columns to project (default: all). | | `--where <predicate>` | Warehouse-native SQL predicate (no leading `WHERE`). | | `--limit <n>` | Max rows to export. | | `--dest-url <url>` | Direct cloud destination (`gs://`, `s3://`). | | `--async` | Return job ID immediately without waiting. | ## Examples ```bash # Export as GeoParquet (waits, prints download URL) carto export --connection carto_dw --source project.dataset.my_table --format geoparquet # Export selected columns with a WHERE predicate and a row limit carto export \ --connection carto_dw \ --source project.dataset.my_table \ --format csv \ --select name,lon,lat \ --where "year = 2025" \ --limit 10000 # Export directly to cloud storage carto export \ --connection carto_dw \ --source project.dataset.my_table \ --format geojson \ --dest-url gs://my-bucket/exports/data.geojson # Kick off async, then poll status separately carto export --connection carto_dw --source project.dataset.big --format csv --async carto export status <jobId> ``` # transfer Transfer data between warehouses. Waits for completion by default. ```bash carto transfer --source-connection <n> --dest-connection <n> --source-table <t> --dest-table <t> carto transfer status <jobId> # Fetch status of an async transfer job ``` {% hint style="info" %} Transfer requires the DuckDB import engine to be enabled for your account. {% endhint %} ## Options | Option | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `--source-connection <name>` | (Required) Source connection name. | | `--dest-connection <name>` | (Required) Destination connection name. | | `--source-table <fqn>` | (Required) Source table. | | `--dest-table <fqn>` | (Required) Destination table. | | `--geography` | Use geography type for spatial data. | | `--overwrite` | Replace the destination table if it already exists. The replacement is staged, so the existing table survives a failed transfer. | | `--target-srid <epsg>` | Reproject geometry to this EPSG code at the destination. Fails if the destination cannot store it. | | `--preserve-source-crs` | Keep the source CRS instead of applying the destination's convention. Fails if the destination cannot store it. | | `--async` | Return job ID immediately without waiting. | `--target-srid` and `--preserve-source-crs` are mutually exclusive. ## Examples ```bash # Transfer from BigQuery to Snowflake carto transfer \ --source-connection bigquery-prod \ --dest-connection snowflake-analytics \ --source-table project.dataset.customers \ --dest-table db.schema.customers # With geography support, async carto transfer \ --source-connection bq-prod \ --dest-connection postgres-dev \ --source-table project.dataset.geo_data \ --dest-table public.geo_data \ --geography --async # Overwrite the destination and reproject to EPSG:4326 carto transfer \ --source-connection bq-prod \ --dest-connection snowflake-analytics \ --source-table project.dataset.parcels \ --dest-table db.schema.parcels \ --overwrite --target-srid 4326 # Poll an async transfer carto transfer status <jobId> ``` # sql Run SQL on your data warehouse using existing connections. Two modes: `query` returns result rows; `job` runs DDL/DML and polls to completion without returning a result set. ## `carto sql query <connection> [sql]` Run a SQL query and return results. Queries are sent as a `POST` (no URL-length limit, 1-minute timeout). ```bash # Query argument carto sql query <connection> "SELECT * FROM dataset.table LIMIT 10" # Read SQL from a file carto sql query <connection> --file query.sql # Pipe via stdin echo "SELECT COUNT(*) FROM dataset.table" | carto sql query <connection> # Bind parameters carto sql query <connection> "SELECT * FROM t WHERE id = @id" --param id=a-001 # JSON output carto sql query <connection> "SELECT * FROM dataset.table" --json ``` **Options:** | Option | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------- | | `--file <path>` | Read SQL from a file. | | `--param <key=value>` | Bind a query parameter. Repeatable. Values are JSON-parsed (number, boolean, array), otherwise treated as a string. | | `--params-json <json>` | Bind query parameters from a JSON object or array, for full type control. Not combinable with `--param`. | ## `carto sql job <connection> [sql]` Run a DDL/DML job. Polls until complete; no timeout. Used when no result set is returned. ```bash # CREATE TABLE carto sql job <connection> "CREATE TABLE dataset.newtable AS SELECT * FROM dataset.oldtable" # INSERT carto sql job <connection> "INSERT INTO dataset.table VALUES (1, 'test')" # Read from a file carto sql job <connection> --file create_table.sql ``` **Use cases:** * `CREATE TABLE` operations. * `INSERT`, `UPDATE`, `DELETE` statements. * Long-running data transformations. * Operations that don't return result sets. ## Input methods (both `query` and `job`) 1. Command argument: `carto sql query myconn "SELECT * FROM table"`. 2. File: `carto sql query myconn --file query.sql`. 3. Stdin: `echo "SELECT * FROM table" | carto sql query myconn`. # lds CARTO Location Data Services from the terminal: geocoding, reverse geocoding, isolines, routing, and origin-destination matrices. Each subcommand uses the provider configured for your account and counts against its quota. Run [`carto lds capabilities`](#carto-lds-capabilities) to see which provider serves each operation and how much quota remains. ```bash carto lds geocode "350 5th Ave, New York, NY" carto lds reverse-geocode 40.4168 -3.7038 carto lds isolines "-3.7038,40.4168" --mode car --range 300,600 --range-type time carto lds routing "-3.7038,40.4168" "-3.6883,40.4531" --mode car carto lds od-matrix --origin "-3.70,40.41" --destination "-3.68,40.45" carto lds capabilities ``` {% hint style="info" %} Coordinates are written `lon,lat` wherever they are packed into a single value (isolines, routing, od-matrix). `reverse-geocode` is the exception: it takes `lat` and `lon` as two separate arguments. {% endhint %} Every subcommand accepts `--options <json>` for provider-specific advanced options, and `--json` for machine-readable output. ## `carto lds geocode [address...]` Geocode one or more addresses into coordinates. Pass addresses as arguments (repeat to batch them into a single request) or read them from a file with `--file`, one per line. At least one address is required, from arguments or `--file`. ```bash # Single address carto lds geocode "350 5th Ave, New York, NY" # Batch several, biased to a country carto lds geocode "Cibeles, Madrid" "Sagrada Familia, Barcelona" --country ES # From a file, one address per line, best match only carto lds geocode --file addresses.txt --limit 1 ``` | Option | Description | | ------------------ | ---------------------------------------------------------------------------- | | `--country <code>` | ISO 3166-1 country code to bias or restrict results (e.g. `US`). | | `--limit <n>` | Maximum candidates per address. | | `--file <path>` | Read addresses from a file, one per line (added to any passed as arguments). | | `--options <json>` | Provider-specific advanced options as a JSON object. | ## `carto lds reverse-geocode <lat> <lon>` Turn a coordinate into an address or place name. Latitude and longitude are separate arguments. ```bash carto lds reverse-geocode 40.4168 -3.7038 carto lds reverse-geocode 40.4168 -3.7038 --lang es --json ``` | Option | Description | | ------------------ | ----------------------------------------------------------- | | `--lang <code>` | Result language where the provider supports it (e.g. `es`). | | `--limit <n>` | Maximum candidates. | | `--options <json>` | Provider-specific advanced options as a JSON object. | ## `carto lds isolines <origin>` Compute an isoline (catchment area) around one origin, given as `lon,lat`. ```bash # 5- and 10-minute drive-time catchments carto lds isolines "-3.7038,40.4168" --mode car --range 300,600 --range-type time # 1 km walking catchment carto lds isolines "-3.7038,40.4168" --mode walk --range 1000 --range-type distance ``` | Option | Description | | --------------------- | ----------------------------------------------------------------------------------- | | `--mode <mode>` | (Required) Travel mode, provider-dependent (e.g. `car`, `walk`, `bike`). | | `--range <values>` | (Required) Comma-separated range values: seconds for `time`, meters for `distance`. | | `--range-type <type>` | (Required) Whether `--range` is `time` or `distance`. | | `--options <json>` | Provider-specific advanced options as a JSON object. | ## `carto lds routing <origin> <destination>` Compute a route between two points, each given as `lon,lat`, optionally via intermediate waypoints. ```bash carto lds routing "-3.7038,40.4168" "-3.6883,40.4531" --mode car # Via waypoints, with full geometry carto lds routing "-3.70,40.41" "-3.68,40.45" \ --mode car \ --waypoints "-3.69,40.42:-3.685,40.44" \ --overview full ``` | Option | Description | | ----------------------------- | --------------------------------------------------------------------------------- | | `--mode <mode>` | (Required) Travel mode, provider-dependent (e.g. `car`, `pedestrian`, `bicycle`). | | `--waypoints <points>` | Intermediate stops as `lon,lat:lon,lat` (colon-separated `lon,lat` pairs). | | `--overview <detail>` | Geometry detail: `simplified` (default) or `full`. | | `--simplify-tolerance <m>` | Fixed simplification tolerance in meters. Ignored with `--overview full`. | | `--include-provider-geometry` | Include the provider's raw geometry in the response metadata. | | `--options <json>` | Provider-specific advanced options as a JSON object. | ## `carto lds od-matrix` Compute an origin-destination travel-time and distance matrix. TravelTime provider only. Supply origins and destinations either as repeatable point flags or as JSON arrays of `[lon,lat]` pairs. ```bash # Repeatable point flags carto lds od-matrix \ --origin "-3.70,40.41" --origin "-3.69,40.42" \ --destination "-3.68,40.45" # JSON arrays of [lon,lat] pairs carto lds od-matrix \ --origins-json '[[-3.70,40.41],[-3.69,40.42]]' \ --destinations-json '[[-3.68,40.45]]' ``` | Option | Description | | ---------------------------- | ---------------------------------------------------------------------------- | | `--origin <lon,lat>` | An origin point. Repeatable. | | `--destination <lon,lat>` | A destination point. Repeatable. | | `--origins-json <json>` | Origins as a JSON array of `[lon,lat]` pairs. Replaces `--origin`. | | `--destinations-json <json>` | Destinations as a JSON array of `[lon,lat]` pairs. Replaces `--destination`. | | `--mode <mode>` | Travel mode, provider-dependent. | | `--options <json>` | Provider-specific advanced options as a JSON object. | ## `carto lds capabilities` Show the account's LDS provider for each operation and its quota (annual, used, remaining). ```bash carto lds capabilities carto lds capabilities --json ``` # org Organization-wide statistics and quotas. ## `carto org stats` View organization statistics, resources, and quota consumption. ```bash carto org stats carto org stats --json ``` The displayed information depends on your permissions: * Regular users see resource counts and basic stats. * Admin users see full organization statistics including quotas. * If access is denied for some sections, partial data is shown with notes. **Surfaces shown (when available):** * **Users** — total, editors, viewers, superadmins, API access tokens. * **Resources** — maps (yours and total), workflows, connections, applications. * **Usage & Quotas** — usage quota, LDS credits, geocoding/isolines, map loads. * **AI Quotas** — Builder Gen AI threads, AI Agents tokens. For an example of the full output, see [Examples → Organization statistics](/carto-for-agents/cli/examples#organization-statistics). # users Manage users and invitations in your CARTO organization. User management commands require admin or superadmin permissions. Regular users may not have access to view all organization users; invitation commands require permission to invite users to the organization. ## Identifying a user Commands that act on a specific user take `--user-id` for a user ID or `--user-email` for an email address. SSO user IDs often contain an `@`, so say which kind you are passing. ```bash carto users get --user-email jane@carto.com carto users get --user-id "samlp|my-sso|jane@carto.com" ``` Quote values containing `|` so your shell does not read it as a pipe. ## `carto users list` List every user in the organization. The command returns the full roster in one call; filter the output when you need a subset. ```bash carto users list carto users list --json | jq '[.[] | select(.role == "Builder")]' carto users list --json | jq '[.[] | select(.email | contains("john"))]' ``` {% hint style="info" %} `--all`, `--page`, `--page-size`, `--role` and `--search` were removed in v0.12.0. The API never applied them, and `--all` did not finish for organizations of 100 or more users. A plain `carto users list` returns everyone. {% endhint %} ## `carto users get` Get detailed information for a user. See [Identifying a user](#identifying-a-user). ```bash carto users get --user-email jatorre@carto.com carto users get --user-id "google-oauth2|123456789" carto users get --user-id "samlp|my-sso|jane@carto.com" --json ``` **Options:** | Option | Description | | ---------------------- | ---------------------------------- | | `--user-id <id>` | Look the user up by user ID. | | `--user-email <email>` | Look the user up by email address. | Output includes the user profile, roles, organization, identities, and groups. ## `carto users invite <email[,email...]> [email...]` Invite one or more users to the organization. Both comma-separated and multi-argument forms are accepted. ```bash # Single user carto users invite user@example.com --role Builder # Default role is Viewer carto users invite user@example.com # Comma-separated carto users invite user1@example.com,user2@example.com,user3@example.com --role Builder # Multiple arguments carto users invite user1@example.com user2@example.com --role Viewer ``` **Options:** | Option | Description | | --------------------------------- | ---------------------------------- | | `--role <Builder\|Viewer\|Guest>` | Role to assign. Default: `Viewer`. | **Available roles:** * **Builder** — full access to create and edit maps, workflows, and connections. * **Viewer** — read-only access to view maps and data. * **Guest** — limited access, typically for external collaborators. ## `carto users invitations` List pending invitations. ```bash carto users invitations carto users invitations --json ``` ## `carto users resendInvitation <invitation-id>` Resend a pending invitation. ## `carto users cancelInvitation <invitation-id>` Cancel a pending invitation. ## `carto users delete` Remove a user from the organization and transfer everything they own to another user. Requires Admin permissions. Both users must be identified, the one being removed and the one receiving their content. See [Identifying a user](#identifying-a-user). ```bash # Remove a user, hand their content to a colleague carto users delete --user-email jane@carto.com --receiver-email bob@carto.com # An SSO user ID that contains an "@" carto users delete --user-id "samlp|my-sso|jane@carto.com" --receiver-email bob@carto.com # The two can be identified differently carto users delete --user-email jane@carto.com --receiver-id "auth0|68c97d3137451d6dabeb86c4" ``` **Options:** | Option | Description | | -------------------------- | -------------------------------------------------- | | `--user-id <id>` | User to remove, by user ID. | | `--user-email <email>` | User to remove, by email address. | | `--receiver-id <id>` | User who receives their content, by user ID. | | `--receiver-email <email>` | User who receives their content, by email address. | **What transfers.** Maps, workflows, connections, API access tokens, assets, named sources, hosted apps, folders, and shortcuts all move to the receiving user, along with any SPA OAuth applications. **What does not.** The removed user's machine-to-machine OAuth applications are deleted rather than transferred, so any integration authenticating as that user stops working. Their recent activity, job history, group memberships, and per-user quota settings are also discarded. {% hint style="warning" %} Deleting a user cannot be undone. If the user being removed is a Builder or an Admin, the receiving user needs Builder privileges or higher, otherwise the command is rejected. You cannot delete your own account this way. {% endhint %} The content transfer runs asynchronously, so the receiving user's maps and workflows may take a moment to appear after the command returns. # activity Query and export detailed activity logs and usage data from your CARTO organization. Useful for analyzing user activity, tracking adoption metrics, and building custom dashboards without needing a data warehouse. **Requirements:** Enterprise Large plan or above. ## `carto activity query` Run SQL against your activity data using DuckDB. The CLI automatically downloads the data (if needed), caches it in `/tmp`, and runs your query. **Smart caching:** the first query for a given date range downloads data (\~10s); subsequent queries with the same range are near-instant (\~0.02s). ```bash # Simple count carto activity query --start-date 2025-10-01 --end-date 2025-10-07 \ --sql "SELECT COUNT(*) as total_events FROM activity" # Maps created per user with email carto activity query --start-date 2025-10-01 --end-date 2025-10-07 --sql " SELECT CAST(a.ts AS DATE) as date, u.email, COUNT(*) AS created_maps FROM activity a JOIN userList u ON json_extract_string(a.data, '$.userId') = u.user_id WHERE a.type = 'MapCreated' GROUP BY date, u.email ORDER BY created_maps DESC LIMIT 10 " # Force fresh download carto activity query --start-date 2025-10-01 --end-date 2025-10-07 --no-cache \ --sql "SELECT type, COUNT(*) FROM activity GROUP BY type ORDER BY COUNT(*) DESC" # JSON output carto activity query --start-date 2025-10-01 --end-date 2025-10-07 --json \ --sql "SELECT COUNT(*) FROM activity" ``` **Options:** | Option | Description | | --------------------- | -------------------------------------------------- | | `--start-date <date>` | Start date (`YYYY-MM-DD`). | | `--end-date <date>` | End date (`YYYY-MM-DD`). | | `--sql <sql>` | DuckDB SQL to execute against the activity tables. | | `--no-cache` | Force fresh download (ignore the `/tmp` cache). | | `--json` | Machine-readable JSON output. | ### Available tables | Table | Columns | | ----------- | --------------------------------------------------------------------------------------------------------------------------------- | | `activity` | `type` (VARCHAR — event type, e.g., `MapCreated`, `WorkflowRun`), `ts` (TIMESTAMP UTC), `data` (VARCHAR — JSON payload). | | `apiUsage` | `ts` (TIMESTAMP — daily), `user_id` (VARCHAR), `metric` (VARCHAR — API method), `amount` (NUMBER), `quota_usage_weight` (NUMBER). | | `userList` | `user_id`, `email`, `role`, `created_at`, `group_ids`. | | `groupList` | `group_id`, `group_alias` — only present if groups are enabled. | ### DuckDB SQL tips * JSON extraction: `json_extract_string(data, '$.userId')`. * Date casting: `CAST(ts AS DATE)`. * Date arithmetic: `current_date - INTERVAL 7 DAY`. For the full schema, see [Activity Data Reference](/carto-user-manual/settings/activity-data/activity-data-reference). ## `carto activity export` Export raw activity data to files. Useful for loading into your own data warehouse for advanced analytics, or for archiving. ```bash # Export all categories carto activity export --start-date 2025-10-01 --end-date 2025-10-07 # Export as Parquet (smaller files, faster queries) carto activity export --start-date 2025-10-01 --end-date 2025-10-07 --format parquet # Export only the activity category carto activity export --start-date 2025-10-01 --end-date 2025-10-07 --category activity # Custom output directory carto activity export --start-date 2025-10-01 --end-date 2025-10-07 --output-dir ~/exports ``` **Options:** | Option | Description | | --------------------- | -------------------------------------------------------- | | `--start-date <date>` | Start date (`YYYY-MM-DD`). | | `--end-date <date>` | End date (`YYYY-MM-DD`). | | `--category <name>` | Limit to a specific category (e.g., `activity`). | | `--format <format>` | Output format. `parquet` recommended for large exports. | | `--output-dir <path>` | Output directory. Defaults to current working directory. | **Use cases:** * **Quick SQL analysis** — `activity query` with no warehouse needed. * **Track adoption** — user activity, map creation, workflow execution. * **Monitor quotas** — API usage and quota consumption by user/team. * **Export to warehouse** — load Parquet into BigQuery/Snowflake for advanced analytics. * **Audit trails** — complete event history for compliance. # admin Superadmin operations: list resources across all users, batch delete, and transfer resources between users. Requires superadmin permissions. ## `carto admin list <resource-type>` List all resources across the organization (not just yours). ```bash carto admin list maps carto admin list workflows carto admin list connections # With pagination and search carto admin list maps --page-size 50 carto admin list connections --search snowflake # Fetch every page carto admin list maps --all carto admin list workflows --all ``` **Resource types:** `maps`, `workflows`, `connections`. **Options:** | Option | Description | | ----------------- | ------------------------------ | | `--page <n>` | Page number. | | `--page-size <n>` | Items per page. | | `--search <term>` | Search by name or description. | | `--all` | Fetch all pages automatically. | ## `carto admin batch-delete <json-body>` Delete multiple resources in a single call. ```bash carto admin batch-delete '{"resource_ids":["map1","map2","workflow1"]}' ``` ## `carto admin transfer <json-body>` Transfer resources from one user to another. ```bash carto admin transfer '{ "from_user": "user1@example.com", "to_user": "user2@example.com", "resource_ids": ["map1", "workflow1"] }' ``` ## `carto admin settings get | apply | diff` Round-trip org-wide administrative settings (basemaps toggles, palettes, maps, connections, workflows, builder-gen-ai, carto-ai) as a single JSON bundle. The same shape that `apply` accepts is what `get` emits, so the three subcommands compose for moving settings between environments or capturing a snapshot for audit. ```bash # Dump the current org settings to stdout carto admin settings get # Or write them to a file carto admin settings get --out settings.json # Preview what would change without writing carto admin settings diff settings.json cat settings.json | carto admin settings diff - # Apply a bundle (per-section PATCH — only the sections present in the file are touched) carto admin settings apply settings.json carto admin settings apply --file settings.json cat settings.json | carto admin settings apply - ``` **Subcommands:** | Subcommand | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `settings get` | Read the current org settings as a JSON bundle. | | `settings apply` | Apply a bundle. Sections present in the bundle are PATCHed individually; sections absent from the bundle are left untouched. | | `settings diff` | Preview what `apply` would change. Pure read-only — no writes. | **Options:** | Option | Description | | --------------- | --------------------------------------------------------------------------------------- | | `--out <file>` | (`get` only) Write the bundle to a file instead of stdout. | | `--file <path>` | (`apply` only) Read the bundle from a file instead of the positional argument or stdin. | # ai AI-related commands: chat with the AI agents configured on your maps (`aifeature`), and access CARTO's LLM proxy with an OpenAI-compatible API (`aiproxy`). ## `carto aifeature aiagent <map-id>` Chat with the AI agent configured on a specific map. The CLI automatically fetches the agent's configuration and token — you just need your regular CARTO authentication. ```bash # Interactive multi-turn conversation carto aifeature aiagent <map-id> # Example session: # You: What are the traffic patterns in this area? # Assistant: Based on the data, I can see... # You: Show me the collision hotspots # Assistant: Here are the areas with highest collisions... # You: exit # One-shot mode carto aifeature aiagent <map-id> "What are the traffic patterns?" # Continue a previous conversation carto aifeature aiagent <map-id> "Tell me more" --conversation-id abc123 # Read message from a file carto aifeature aiagent <map-id> --file test-query.txt # Pipe via stdin echo "Analyze the collision data" | carto aifeature aiagent <map-id> # JSON output carto aifeature aiagent <map-id> "Summarize the data" --json ``` **Options:** | Option | Description | | ------------------------ | ----------------------------------------------------------- | | `--conversation-id <id>` | Continue a previous conversation by ID. | | `--file <path>` | Read the message from a file. | | `--json` | Machine-readable JSON output (for automation and CI tests). | **How it works:** * Connects to your map's configured AI agent. * The agent has access to map data, workflows, and configured tools. * Streams responses in real time. * Executes backend tools (workflows, SQL) automatically. * Tracks conversation history for multi-turn interactions. **Use cases:** * **Test agent instructions** — validate behavior during development. * **Debug agent tools** — see which workflows/tools the agent invokes. * **Automated testing** — agent quality scripts. * **Agent development** — rapidly iterate on configuration. * **CI/CD integration** — gate deployments on agent validation. ## `carto aiproxy` Access CARTO's LLM infrastructure directly with an OpenAI-compatible API. Use any available model for custom tasks without going through the AI Features layer. The CLI automatically connects to CARTO's LiteLLM service at `https://litellm-{tenant}.api.carto.com` using your CARTO authentication. ### `carto aiproxy info` Get connection information for external tools. ```bash carto aiproxy info ``` Example output: ``` CARTO LiteLLM Proxy Configuration API Mode: OpenAI Compatible API Host: https://litellm-gcp-us-east1.api.carto.com API Base URL: https://litellm-gcp-us-east1.api.carto.com/v1 API Key: eyJhbGciOiJSUzI1NiIs... Endpoints: Chat completions: /v1/chat/completions Completions: /v1/completions Embeddings: /v1/embeddings Models: /v1/models ``` ### `carto aiproxy models` List available models. ```bash carto aiproxy models ``` ### `carto aiproxy chat <message>` Send a chat message to a model. ```bash # Simple chat carto aiproxy chat "What is 2+2?" --model gpt-4 # With a system prompt carto aiproxy chat "Analyze this data pattern" \ --model gemini-2.5-flash \ --system "You are a geospatial data analyst" # Control generation parameters carto aiproxy chat "Write a haiku about maps" \ --model gpt-4 \ --temperature 1.5 \ --max-tokens 100 # Read message from a file carto aiproxy chat --file prompt.txt --model gpt-4 # Pipe via stdin echo "Explain quantum physics simply" | carto aiproxy chat --model gpt-4 # JSON output carto aiproxy chat "Hello" --model gpt-4 --json ``` **Options:** | Option | Description | | ------------------- | ----------------------------------------------------------------------------- | | `--model <name>` | (Required) Model to use. Run `carto aiproxy models` to list available models. | | `--system <text>` | System prompt to set agent behavior. | | `--temperature <n>` | Sampling temperature, 0–2 (default: 1). Higher = more creative. | | `--max-tokens <n>` | Maximum tokens in the response. | | `--top-p <n>` | Top-p sampling, 0–1 (default: 1). | | `--file <path>` | Read the message from a file. | | `--json` | Output the raw JSON response. | **Use cases:** * **Quick LLM access** — use CARTO's LLM infrastructure for any task. * **Prototyping** — test prompts before building AI Features. * **Data analysis** — get AI insights on your geospatial data. * **Custom scripts** — integrate LLM capabilities into automation. * **Model comparison** — test the same prompt against different models. # app Publish a built frontend as a CARTO-hosted app, or prepare a public build of one you host yourself. A hosted app is a static bundle served at `<workspace-url>/app/<slug>/` behind your organization login; it runs as the signed-in viewer and calls the CARTO API directly. [Hosting your application in CARTO](/carto-for-developers/guides/build-a-hosted-application) walks through building one, and the [Hosted Apps reference](/carto-for-developers/reference/hosted-apps) describes the manifest and the runtime contract; this page is the command reference. {% hint style="info" %} **Private Preview:** Hosted Apps is available to selected accounts during its Private Preview. To request access, contact your CARTO representative. {% endhint %} When Hosted Apps is not enabled for your account, `carto app deploy` exits 1 and explains how to request access (`--json` adds `"code": "hosted-apps-feature-disabled"`). The other commands keep working, so apps already deployed can still be shared, rolled back or deleted. On a CARTO deployment that predates Hosted Apps, the commands that manage hosted apps fail the same way. ## The bundle and `carto.json` The directory you deploy or package is a built static bundle: `index.html` at the root, at most 1000 files, 25 MB per file and 50 MB in total. At runtime the app fetches `./carto-info.json` (relative to its own path) to get the viewer's access token and the CARTO API base URL. An optional `carto.json` at the bundle root declares the backend the app needs: the connections it reads from and the named sources (parametrized SQL) it invokes by name. It is read at deploy or package time and never served. Connections may also list `tables` and `statements`; they only scope the public token when packaging, and `carto app deploy` strips them. `carto app schema` prints the full reference for both files; [App manifest](/carto-for-developers/reference/hosted-apps/app-manifest) documents `carto.json` field by field. ## `carto app deploy <directory>` Package and upload a bundle, provision the backend declared in `carto.json`, and serve the new version. ```bash carto app deploy ./dist --name "Store Explorer" carto app deploy ./dist --slug store-explorer --connection warehouse=my_bigquery carto app deploy ./dist --json ``` **Options:** | Option | Description | | -------------------------- | ---------------------------------------------------------------------- | | `--name <name>` | Display name (default: directory basename). | | `--slug <slug>` | URL slug: lowercase, digits, hyphens (default: slugified name). | | `--version <label>` | Version label, unique per deploy (default: UTC timestamp). | | `--description <text>` | Optional description. | | `--connection handle=name` | Map a `carto.json` connection handle to a real connection. Repeatable. | ## `carto app list` List the hosted apps available to you. ```bash carto app list ``` ## `carto app versions <slug>` List an app's deployed versions and which one is active. ```bash carto app versions store-explorer ``` ## `carto app rollback <slug> [version]` Serve an already-deployed version. Only the bundle changes; the provisioned backend is untouched. ```bash carto app rollback store-explorer 2026-09-01T10:00:00Z carto app rollback store-explorer --version 2026-09-01T10:00:00Z ``` ## `carto app share <slug>` Choose who can open the app: only you, everyone in the organization, or specific groups and users (by id). ```bash carto app share store-explorer --org carto app share store-explorer --group <group-id>,<group-id> carto app share store-explorer --user <user-id> carto app share store-explorer --private ``` **Options:** | Option | Description | | --------------- | --------------------------------------------- | | `--private` | Only you can open it. | | `--org` | Everyone in your organization. | | `--group <ids>` | Share with specific groups (comma-separated). | | `--user <ids>` | Share with specific users (comma-separated). | ## `carto app delete <slug>` Delete the app: every deployed version and the named sources it registered. Asks for confirmation unless `--yes` is passed. ```bash carto app delete store-explorer --yes ``` ## `carto app schema [section]` Print the JSON Schema for `carto.json` (the deploy manifest) and `carto-info.json` (the runtime bootstrap), with every field described. Runs offline. ```bash carto app schema carto app schema connection carto app schema carto-info ``` Sections: `manifest` (default), `connection`, `source`, `migration`, `carto-info`. ## `carto app check <directory>` Safety report before a bundle goes public. Runs offline. It derives the grants a public token would need from `carto.json` (tables, exact statements, named sources), blocks DDL, multi-statement SQL and line comments, flags writes wherever they appear in a statement, and scans every non-binary file for `.env` files, known secret shapes (JWTs, private keys, cloud and Git host keys) and a stray `carto-info.json`. Exit code 1 when something blocks. ```bash carto app check ./dist carto app check ./dist --allow-writes --connection warehouse=my_bigquery ``` **Options:** | Option | Description | | -------------------------- | ------------------------------------------------------------------------- | | `--slug <slug>` | Slug used to name registered sources (default: slugified directory name). | | `--name <name>` | Display name the slug is derived from. | | `--connection handle=name` | Map a `carto.json` connection handle to a real connection. Repeatable. | | `--allow-writes` | Accept `INSERT` / `UPDATE` / `DELETE` grants; otherwise they block. | ## `carto app package <directory>` Build a public version of a bundle you host yourself. It runs the check, registers the manifest's named sources, mints one least-privilege API Access Token named `app:<slug>@<timestamp>-<nonce>` locked to the referer in `--url` (path included when the URL has one), verifies the token by replaying the allowed calls and probing a forbidden one, revokes earlier `app:<slug>` tokens so re-runs are idempotent, and writes `<out>/carto-info.json` next to a copy of the bundle. The package is recorded in `.carto/packages.json`. The token is masked on stdout unless `--show-token` is passed; it is always written to `carto-info.json`. Read-only tokens expire in one year, tokens with write grants in 30 days; `--expires` changes either. ```bash carto app package ./dist --url https://apps.example.com/store-explorer carto app package ./dist --url https://apps.example.com/store-explorer --dry-run carto app package ./dist --url https://apps.example.com/store-explorer --allow-writes --expires 2w carto app package ./dist --update-referer https://apps.example.com/v2/store-explorer ``` **Options:** | Option | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `--out <dir>` | Output folder (default: `<directory>-public`). | | `--url <public-url>` | Where the app will be hosted; locks the token to that referer. | | `--slug <slug>` | Slug used to name registered sources and the token (default: slugified name). | | `--name <name>` | Display name (default: directory basename). | | `--connection handle=name` | Map a `carto.json` connection handle to a real connection. Repeatable. | | `--allow-writes` | Grant `INSERT` / `UPDATE` / `DELETE` statements; the token then expires in 30 days unless `--expires` says otherwise. | | `--expires <when>` | Token expiry: an ISO date, `1d` / `2w` / `6m` / `1y`, or `never` (read-only tokens only). Default: `1y`, or `30d` with writes. | | `--dry-run` | Run the check and show the plan; mint and write nothing. | | `--skip-verify` | Skip replaying the grants against the new token. | | `--show-token` | Print the full token instead of masking it. | | `--update-referer <url>` | Rotate the recorded token so it is restricted to this public URL. | `deploy` publishes an internal app (organization login, viewer token). `package` produces a public one (scoped API Access Token, hosted by you). # Examples End-to-end walkthroughs combining several commands. For per-command details see the [command reference](/carto-for-agents/cli/command-reference). ## Authentication workflow ```bash # Interactive browser-based login using OAuth 2.0 + PKCE carto auth login # This will: # 1. Display an authorization URL # 2. Open your browser (you may need to copy/paste the URL) # 3. Wait for you to complete the login process # 4. Capture your access token and user information # 5. Store credentials in ~/.carto_credentials.json # 6. Configure the API URL based on your tenant # Check authentication status carto auth status # Show current user information carto auth whoami # Returns: user_id, name, email, account info, roles # Switch between profiles carto auth use production carto auth use staging ``` ## Managing application credentials ```bash # List all credentials carto credentials list carto credentials list tokens # Create an API Access Token for your application carto credentials create token \ --connection carto_dw \ --source "demo_tables.*" \ --apis sql,maps # Create SPA OAuth Client for web applications carto credentials create spa \ --title "My Dashboard" \ --callback "https://mydash.com/callback" # Create M2M OAuth Client for backend services carto credentials create m2m \ --title "ETL Service" # Get token details carto credentials get token <token-id> # Delete a credential carto credentials delete token <token-id> ``` ## Browsing and managing resources ```bash # List maps with filters (enhanced display shows owner, privacy, views, tags) carto maps list --search sales --page-size 20 # List only your maps carto maps list --mine # Pagination carto maps list --page 1 --page-size 10 carto maps list --page 2 --page-size 10 # Fetch all pages automatically with --all carto maps list --all carto maps list --mine --all carto workflows list --all --search "project" # Get detailed info for a specific map carto maps get 69b0e7cc-026a-4feb-87bb-a82cc6ac5189 # Output shows: # - Map metadata (title, owner, privacy, views, collaborative, agent enabled) # - Datasets and their connections # - Map URL # JSON output for scripting (or AI agents) carto maps list --json | jq '.data[].id' # Delete a map carto maps delete map_abc123 ``` ## Creating a Builder map from JSON `carto maps create` accepts a round-trippable bundle from a positional JSON string, a filesystem path, or stdin. Pre-flight validation runs before any write, so broken bundles reject without creating an orphan map. ```bash # Minimal bundle — title, connection, and one dataset rendered as a tileset layer cat > stores.map.json <<'JSON' { "title": "Retail stores", "connectionId": "12345678-1234-1234-1234-123456789abc", "privacy": "private", "datasets": [ { "id": "stores-ds", "type": "table", "source": "carto-demo-data.demo_tables.retail_stores", "connectionId": "12345678-1234-1234-1234-123456789abc" } ], "keplerMapConfig": { "config": { "visState": { "layers": [ { "id": "stores-layer", "type": "tileset", "config": { "dataId": "stores-ds", "label": "Stores", "color": [255, 100, 50], "visConfig": { "radius": 10 } } } ] }, "mapStyle": { "styleType": "positron" } } } } JSON # Validate locally (no network), then create carto maps validate < stores.map.json carto maps create < stores.map.json # Or chain in one go carto maps create ./stores.map.json --json | jq '.builderUrl' ``` For the full schema and authoring patterns, see [`carto maps schema`](/carto-for-agents/cli/command-reference/maps#carto-maps-schema-section) and the [`carto-create-builder-maps`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-builder-maps) skill. ### Round-trip: edit an existing map ```bash # Get the map as a round-trippable bundle, edit, and update carto maps get abc123 --json > /tmp/map.json jq '.title = "Q3 Dashboard"' /tmp/map.json | carto maps update abc123 # Update + publish in one call so shared/public viewers see the changes carto maps update abc123 < /tmp/map.json --publish ``` ### Screenshot a map {% hint style="info" %} `carto maps screenshot` is **experimental**. Its flags, render engines, and output may change in future releases. {% endhint %} ```bash # Default light engine — layers + basemap, no widgets carto maps screenshot abc123 -o map.png # Recenter and hide chrome carto maps screenshot abc123 --lat 40.42 --lng -3.70 --zoom 12 --hide-overlays # Full CARTO Builder viewer (widgets, legends, popups) — heavier carto maps screenshot abc123 --render-engine full ``` ## Creating a Workflow from a bundle `carto workflows create --file <bundle.json>` takes a Workflows bundle and provisions the nodes, edges, and metadata in a single call. ```bash # Minimal — pipeline that reads a table, filters it, and writes back cat > cycle-pipeline.workflow.json <<'JSON' { "title": "Cycle network — existing routes only", "connectionId": "12345678-1234-1234-1234-123456789abc", "config": { "schemaVersion": "1.0.0", "connectionProvider": "bigquery", "useCache": false, "nodes": [ { "id": "src", "type": "source", "data": { "name": "ReadTable", "inputs": [ { "name": "source", "value": "demo_tables.bristol_cycle_network" } ] }, "position": { "x": 100, "y": 100 } }, { "id": "filter", "type": "generic", "data": { "name": "native.where", "inputs": [ { "name": "expression", "value": "r_status = 'Existing'" } ] }, "position": { "x": 300, "y": 100 } } ], "edges": [ { "id": "e1", "source": "src", "target": "filter", "sourceHandle": "out", "targetHandle": "source" } ] }, "tags": ["analytics", "cycle-data"] } JSON # Validate offline (Zod-only, no warehouse calls), then create carto workflows validate --file cycle-pipeline.workflow.json carto workflows create --file cycle-pipeline.workflow.json # Full warehouse-side check before merging the bundle to a repo carto workflows verify --file cycle-pipeline.workflow.json --connection carto_dw ``` ### Browse the component catalog Workflows are composed from components — `native.where`, `native.customsql`, `native.joinv2`, and many more. Browse the catalog for a connection (so extensions and stored procedures show up too): ```bash # All Joins components for a BigQuery connection carto workflows components list --connection carto_dw --group Joins # Full input/output signatures for the components you'll use carto workflows components get native.customsql,native.joinv2 --connection carto_dw --json ``` ### Run + publish as an MCP tool ```bash # Execute the workflow carto workflows run abc123 # Make it callable from the CARTO MCP Server (agents will see it as a tool) carto workflows mcp publish abc123 ``` ## Copying maps and workflows between organizations A common pattern is promoting maps and workflows between environments — staging to production, customer A to customer B, or one region to another. The CLI handles connection mapping automatically and validates source accessibility before copying. **Prerequisites:** authenticate to both organizations using [named profiles](/carto-for-agents/cli/authentication#multiple-profiles). You'll need the **ID** of the map or workflow to copy. Get it from the CARTO Workspace (three-dot menu on the card, or from the URL), or search by name with `carto maps list --search "<name>"` / `carto workflows list --search "<name>"`. ```bash # Auto-map connections by name (default, recommended) carto maps copy <map-id> --dest-profile <profile-name> carto workflows copy <workflow-id> --dest-profile <profile-name> ``` By default, CARTO will try to map each connection used by the source resource to a connection **with the same name** in the destination organization. If a Snowflake connection is called `production` in both orgs, the copy works without further configuration. When connection names differ, supply an explicit mapping: {% code overflow="wrap" %} ```bash carto maps copy <map-id> --dest-profile <profile-name> \ --connection-mapping "dev-bq=prod-bq,dev-postgres=prod-postgres" ``` {% endcode %} {% code overflow="wrap" %} ```bash carto workflows copy <workflow-id> --dest-profile <profile-name> \ --connection <connection-name> ``` {% endcode %} {% hint style="info" %} The CLI assumes mapped connections **have the same data access permissions**. If they don't, the copied resources will fail to load. {% endhint %} {% hint style="info" %} Copying does not delete the original resource. {% endhint %} ### Smart connection mapping The CLI handles connection mapping with three strategies, in priority order: 1. **Auto-mapping by name (default)** — match connections by name between source and destination. 2. **Manual mapping** — explicit pairs via `--connection-mapping`. 3. **Legacy single connection** — use one connection for all datasets via `--connection`. ```bash # Auto-map (recommended) carto maps copy abc123 --dest-profile production # → Automatically maps: bigquery-dev → bigquery-dev, snowflake → snowflake # Manual mapping for renamed connections carto maps copy map456 \ --source-profile staging \ --dest-profile production \ --connection-mapping "bigquery-dev=bigquery-prod,snowflake-staging=snowflake-prod" # Legacy: single connection for all datasets carto maps copy xyz789 --dest-profile prod --connection prod-bigquery # Combine options carto maps copy map456 \ --dest-profile production \ --connection-mapping "dev-bq=prod-bq" \ --title "Production Sales Dashboard" \ --keep-privacy ``` **How copy works:** 1. Fetches the source map configuration and all datasets. 2. Identifies all unique connections used by the map. 3. Resolves each connection in priority order: manual mapping → auto-map by name → legacy single connection. 4. Validates that all destination connections exist (fails fast if any are missing). 5. **Validates that dataset sources are accessible** in the destination using SQL dry-run queries (`WHERE 1=0`). Tests permissions and existence without transferring data. Fails if any source is inaccessible (unless `--skip-source-validation`). 6. Creates the new map and datasets with resolved connections. 7. Updates the map configuration with the new dataset IDs. 8. Preserves privacy settings if `--keep-privacy` is set. **Connection resolution scenarios:** *Scenario 1 — Perfect match (auto-mapping):* ```bash carto maps copy abc123 --dest-profile prod # Source has: bigquery-dev, snowflake-analytics # Destination has: bigquery-dev, snowflake-analytics # ✅ Success — both auto-mapped by name ``` *Scenario 2 — Renamed connections (manual mapping):* ```bash carto maps copy abc123 --dest-profile prod \ --connection-mapping "bigquery-dev=bigquery-prod,snowflake-analytics=snowflake-prod" # ✅ Success — both manually mapped ``` *Scenario 3 — Mixed (manual + auto):* ```bash carto maps copy abc123 --dest-profile prod --connection-mapping "old-conn=new-conn" # Source has: old-conn, shared-connection # Destination has: new-conn, shared-connection # ✅ Success — old-conn mapped manually, shared-connection auto-mapped ``` *Scenario 4 — Missing connection:* ```bash carto maps copy abc123 --dest-profile prod # Source has: bigquery-dev, snowflake-analytics # Destination has: bigquery-dev only # ❌ Fails with clear error: # Missing connections in destination organization: # • "snowflake-analytics" (used by 3 datasets) # Solutions: # 1. Create missing connections in destination # 2. Use --connection-mapping to map to different names ``` *Scenario 5 — Source validation failure:* ```bash carto maps copy abc123 --dest-profile prod --connection-mapping "dev-bq=prod-bq" # Connections mapped successfully, but... # ❌ Source validation failed - datasets cannot access their data sources: # • "NYC Traffic" → my-project.dataset.traffic_table # Error: Permission bigquery.tables.get denied on table (or it may not exist) # Solutions: # 1. Grant access to these tables in the destination connection # 2. Ensure tables/views exist in the destination data warehouse # 3. Use --skip-source-validation to create the map anyway ``` *Scenario 6 — Skip source validation (intentional broken map):* ```bash carto maps copy abc123 --dest-profile prod \ --connection-mapping "dev-bq=prod-bq" \ --skip-source-validation # ✅ Success — map created but datasets won't load data until access is fixed ``` ### Troubleshooting **Error: "Connection 'X' not found in destination organization"** * Run `carto connections list --profile <dest-profile>` to see available connections. * Create the missing connection in the destination organization. * Use `--connection-mapping` to map to a different name. **Error: "Source validation failed - datasets cannot access their data sources"** * The destination connection lacks permission to access the source tables/queries. * Grant the necessary permissions in your data warehouse (BigQuery, Snowflake, …). * Verify table names/paths are correct and exist in the destination. * Use `--skip-source-validation` if you want to create the map anyway and fix access later. **Map created but visualizations don't load** * This shouldn't happen with validation enabled (the default). * If you used `--skip-source-validation`, check dataset connections and permissions. ## Organization statistics ```bash # View organization statistics and quotas carto org stats # Example output: # === Organization Statistics === # # Users # Total users: 184 # Editor users: 179 # Viewer users: 1 # Superadmin users: 2 # API Access Tokens: 2,374 # # Resources # Maps: 3,792 (2,897 public) # All users maps: 13,624 # Workflows: 872 # Connections: 569 # Applications: 201 # # Usage & Quotas # Usage quota: 7,702,490 # LDS credits: 1,069,663 of 15,000,000 (7%) # Map loads: 53,194 # # AI Quotas # Builder Gen AI: 0 of 250 threads # AI Agents tokens: 292,187 available # JSON output for scripting carto org stats --json ``` The displayed information depends on your permissions: * **Regular users** — see resource counts and basic stats. * **Admin users** — see full organization statistics including quotas. * **Access denied** for some stats — partial data is shown with notes. ## User management ```bash # List all users carto users list # Filter by role carto users list --role Builder carto users list --role Viewer --all # Search for specific users carto users list --search "john" carto users list --search "@company.com" # Get detailed info, by email or by user ID carto users get --user-email jatorre@carto.com carto users get --user-id "google-oauth2|123456789" # SSO user IDs often contain an "@" — say which kind you are passing carto users get --user-id "samlp|my-sso|jane@company.com" # Remove a user and hand their maps, workflows and connections to a colleague carto users delete --user-email jane@company.com --receiver-email bob@company.com # Invite a single user carto users invite newuser@company.com --role Builder # Invite multiple users at once carto users invite user1@company.com,user2@company.com --role Viewer # Check pending invitations carto users invitations # JSON output for automation carto users list --json | jq '.[] | {email, roles: .app_metadata.roles}' ``` ## Activity data analysis Query activity data with DuckDB SQL — no data warehouse needed. The first query with a given date range downloads data (\~10s); subsequent queries are instant from the local cache. ```bash # Simple count carto activity query --start-date 2025-10-01 --end-date 2025-10-07 \ --sql "SELECT COUNT(*) as total_events FROM activity" # Maps created per user, joined with userList for emails carto activity query --start-date 2025-10-01 --end-date 2025-10-07 --sql " SELECT CAST(a.ts AS DATE) as date, u.email, COUNT(*) AS created_maps FROM activity a JOIN userList u ON json_extract_string(a.data, '$.userId') = u.user_id WHERE a.type = 'MapCreated' GROUP BY date, u.email ORDER BY created_maps DESC LIMIT 10 " # User activity by role carto activity query --start-date 2025-10-01 --end-date 2025-10-07 --sql " SELECT u.email, u.role, COUNT(*) as events FROM activity a JOIN userList u ON json_extract_string(a.data, '$.userId') = u.user_id GROUP BY u.email, u.role ORDER BY events DESC " # Export raw files for loading into your warehouse carto activity export --start-date 2025-10-01 --end-date 2025-10-07 --format parquet ``` See [`activity` command reference](/carto-for-agents/cli/command-reference/activity) for the full schema and DuckDB syntax tips. ## Chatting with a map's AI agent ```bash # Interactive multi-turn conversation carto aifeature aiagent <map-id> # One-shot carto aifeature aiagent <map-id> "What are the traffic patterns?" # Continue a previous conversation carto aifeature aiagent <map-id> "Tell me more" --conversation-id abc123 # Pipe a message echo "Analyze the collision data" | carto aifeature aiagent <map-id> # JSON for automation / CI agent quality tests carto aifeature aiagent <map-id> "Summarize the data" --json ``` Useful for testing agent instructions during development, debugging which workflows the agent invokes, and integrating agent validation into CI pipelines. # Release notes This page tracks user-visible changes to the [CARTO CLI](/carto-for-agents/cli). For the full engineering changelog, see the source repository. {% updates %} {% update date="2026-10-01" %} ## v0.13.0 This release brings the new [Builder map layout](/carto-user-manual/maps/map-layout) to the CLI. You can now create and update maps with a floating or two-column widgets panel, full-width widgets and a set order for the parameters bar, and `carto maps validate` checks a map the same way Builder and the CARTO MCP server do. **Requirements** Changed * The CLI now needs **Node.js 22 or later**. Check with `node --version` and upgrade Node before you run `npm i -g @carto/carto-cli`. **Maps** New * [`carto maps schema widgetspanellayout`](/carto-for-agents/cli/command-reference/maps) documents the widgets panel layout, set in `keplerMapConfig.config.widgetsPanelLayout`. Use `columns` (`1`, or `2` for widgets side by side) and `placement` (`docked` next to the map, or `floating` as a card over it). Without it, a map uses one docked column. With two columns, a widget with `fullWidth: true` takes a whole row. * [`carto maps schema sqlparameters`](/carto-for-agents/cli/command-reference/maps) explains that the order of `sqlParameters` is the order of the parameters bar, from left to right. Changed * `carto maps validate` and `carto maps schema` follow the same map rules as Builder and the CARTO MCP server, so a map that passes validation opens in Builder. When something is wrong, the message names the field and says how to fix it. * `carto maps validate` rejects settings Builder would otherwise ignore or replace without telling you. For example, a widgets panel layout with `columns` other than `1` or `2`, a layer that points to a dataset missing from the map, or an AI Agent with more than four conversation starters. Maps saved from Builder pass as they are. {% endupdate %} {% update date="2026-09-23" %} ## v0.12.0 The headline of this release is **connection sharing from the terminal**: share a connection with your organization, with specific people or with groups, and take that access back again, without opening the Workspace. **Connections** New * New [`carto connections share`](/carto-for-agents/cli/command-reference/connections) and [`carto connections unshare`](/carto-for-agents/cli/command-reference/connections): share a connection with the whole organization (`--org`), with specific users by email (`--with`) or with groups by name or id (`--group`), list who has access (`--list`), and remove access again. New grants are added to what the connection already has. Sharing with users or groups needs a CARTO platform that supports connection access policies; on an older Self-hosted deployment the command stops with an upgrade message before changing anything. [Sharing a connection](/carto-user-manual/connections/sharing-a-connection) in the user manual explains how a shared connection behaves for the people who receive it. * [`carto connections get`](/carto-for-agents/cli/command-reference/connections) shows who the connection is shared with. **Imports** New * [`carto import`](/carto-for-agents/cli/command-reference/imports) tells you when an import finished but lost rows. The job ends as `completed_with_warnings`, which the CLI treats as a success (the table exists), and it prints how many rows were dropped and why: rows without a readable location are in the table without geometry, rows with formatting errors were not imported. `--json` carries `metadata.droppedRows`, `droppedRowReasons` and `droppedRowsByReason`. Fixed * `carto import` streams the file to the upload URL instead of reading it into memory first, so files between 2 GiB and the 5 GB limit now import. They previously failed with `File size (...) is greater than 2 GiB`. **Credentials** Fixed * `carto credentials update token --add-grant '<connection>,<SQL>'` keeps the whole SQL source: only the first comma separates the connection from the source. A malformed value now fails instead of silently storing a partial grant, and the source is required (pass `*` to grant every source). * `carto credentials update token --connection <name> --source <source>` adds a grant, as `create token` does. Both flags were previously accepted and ignored. * `carto credentials --help` documents the `update` flags (`--add-grant`, `--connection` with `--source`, `--add-api`, `--referers`, `--json-body`). **Authentication** Fixed * `carto auth whoami` on an M2M profile reports the service identity (client id, account, acting user, API base URL, token expiry) instead of failing with `404 User not found`. * After `carto auth login` with an account that belongs to no CARTO organization, commands now explain that an organization has to be created in the web app first, instead of asking to log in again. **AI** Fixed * `carto aiproxy chat` and `carto ai` no longer answer "Authentication required" when your organization is not allowed to use the requested model. The proxy's own message is printed, including the models you can use; the login hint is kept for a session that is really invalid. Other proxy errors show their message plus `(HTTP n)`. **Output** Changed * Backend failures are shown from the platform's error contract (title, error, detail), never from the raw response body, so a server stack trace can no longer appear in CLI output. `--json` error codes and per-field details are unchanged. **Configuration** Fixed * The CLI honours `NO_PROXY` / `no_proxy` alongside `HTTPS_PROXY` / `HTTP_PROXY`, as curl and git do. Hosts it matches (exact host, `.domain` suffix, `*.domain`, `host:port`, `*`) are reached directly. Previously every request went through the proxy, so against a Self-Hosted instance on an internal-only hostname `carto auth login` worked but every tenant command failed with the proxy's own DNS error page. `carto activity` downloads now also use the configured proxy. See [Proxies](/carto-for-agents/cli/configuration#proxies). **Users** Breaking changes * [`carto users list`](/carto-for-agents/cli/command-reference/users) drops `--all`, `--page`, `--page-size`, `--role` and `--search`. The API never implemented them: every call returned the organization's full roster, and `--all` never finished for organizations of 100 or more users. A plain `carto users list` returns everyone; filter the output instead, for example `carto users list --json | jq '[.[] | select(.email | contains("ana"))]'`. **Hosted apps** New * The [`carto app`](/carto-for-agents/cli/command-reference/app) command group now appears in `carto --help` and in the command catalogue. It requires the Hosted Apps feature on your account; when the feature is not available, or the CARTO deployment predates it, the commands say so and explain how to request access instead of failing with a 404 (`--json` adds `"code": "hosted-apps-feature-disabled"`). * [`carto app schema [section]`](/carto-for-agents/cli/command-reference/app) prints the JSON Schema for `carto.json` (the deploy manifest) and `carto-info.json` (the runtime bootstrap), with every field described. Runs offline. * [`carto app check <dir>`](/carto-for-agents/cli/command-reference/app) is an offline safety report before a bundle goes public: the grants a public token would need, blocked SQL (DDL, multi-statement, line comments, writes unless `--allow-writes`), and a secret scan of the bundle. Exit 1 when blocked. * [`carto app package <dir>`](/carto-for-agents/cli/command-reference/app) builds a public version of a bundle you host yourself: registers the manifest's named sources, mints one least-privilege API Access Token locked to `--url` (one year for read-only grants, 30 days with writes, `--expires` to change), verifies it, revokes the earlier tokens for the slug, and writes `carto-info.json` next to a copy of the bundle. `--dry-run`, `--skip-verify`, `--show-token`, `--update-referer`. * `carto.json` connections accept `tables` and `statements`, used only to scope the public token when packaging; `carto app deploy` ignores them. **Agents** New * Entries in `carto --commands --json` can carry a `docs` deep link to their reference page, so an agent can point a user at the documentation for the command it just ran. * [`carto maps schema`](/carto-for-agents/cli/command-reference/maps) and [`carto workflows schema`](/carto-for-agents/cli/command-reference/workflows) serve the same section catalogue the MCP server now exposes to agents. Output is unchanged except that ten sections gain a root description, and strings that told the reader to run a CLI command now name the capability instead. {% endupdate %} {% update date="2026-09-01" %} ## v0.11.0 The headline of this release is **stroke styles and polygon fill patterns**, now available when you author maps from the terminal. A map written with the CLI can carry the same styling a Builder user sets by hand. **Maps** New * Layer `visConfig` accepts **stroke styles** on line geometries and polygon borders: `lineStyle` (`solid`, `dashed`, `dotted`), `dashArray` as a `[dash, gap]` pair relative to the stroke width, and `lineStyleRange` to drive the style from a column when `lineStyleField` is set. * Layer `visConfig` accepts **polygon fill patterns**: `fillPatternEnabled` switches a polygon from solid fill to pattern, `fillPattern` selects one of `hlines`, `vlines`, `diag-left`, `diag-right`, `cross-hatch`, `dots`, `checker`, `fillPatternDensity` takes `small`, `medium` or `large`, `fillPatternSize` scales the pattern from `0.1` to `5` (`1` = 100%), and `fillPatternRange` drives the pattern from a column when `fillPatternField` is set. Per-category entries additionally accept `solid` (flat fill color) and `none` (unpainted). * [`carto maps schema`](/carto-for-agents/cli/command-reference/maps) reports the new fields, so agents can discover them without reading these notes. Builder renders stroke styles and fill patterns on **tileset (`mvt`)** layers. `h3` and `quadbin` layers accept the same fields — so a stored map survives a future re-enable — but do not render them yet. For what these look like in Builder, see [Stroke styles](/carto-user-manual/maps/layers#stroke-styles) and [Fill patterns](/carto-user-manual/maps/layers#fill-patterns) in the user manual. **Agents** Breaking changes * Map writes now reject agent configs that exceed the caps Builder's agent dialog enforces, instead of accepting them and producing a map that Builder cannot subsequently edit. [`carto maps create`](/carto-for-agents/cli/command-reference/maps) and [`update`](/carto-for-agents/cli/command-reference/maps) fail when `config.useCase` is over 500 characters, `config.introduction.starters` has more than 4 entries, `config.introduction.welcome` is over 300 characters, or any single starter is over 100 characters. A bundle with more than 4 starters previously saved and then failed the viewer with a 500. Trim these fields to bring an existing bundle back within the caps. {% endupdate %} {% update date="2026-08-31" %} ## v0.10.2 The headline of this release is **Location Data Services from the terminal**: geocoding, reverse geocoding, isolines, routing, and origin-destination matrices, all under the new [`carto lds`](/carto-for-agents/cli/command-reference/lds) command group. **Location Services** New * New [`carto lds`](/carto-for-agents/cli/command-reference/lds) command group brings CARTO Location Data Services to the terminal: [`geocode`](/carto-for-agents/cli/command-reference/lds), [`reverse-geocode`](/carto-for-agents/cli/command-reference/lds), [`isolines`](/carto-for-agents/cli/command-reference/lds), [`routing`](/carto-for-agents/cli/command-reference/lds), [`od-matrix`](/carto-for-agents/cli/command-reference/lds), and [`capabilities`](/carto-for-agents/cli/command-reference/lds) (which reports your provider and remaining quota per operation). Every subcommand supports `--json`. **Transfer** New * [`carto transfer`](/carto-for-agents/cli/command-reference/transfer) gains `--overwrite` to replace an existing destination table (staged, so the current table survives a failed transfer), `--target-srid <epsg>` to reproject geometry at the destination, and `--preserve-source-crs` to keep the source CRS instead of applying the destination's convention. **SQL** Breaking changes * [`carto sql query`](/carto-for-agents/cli/command-reference/sql) no longer accepts `--cache`. The flag issued a cached `GET` that no longer cached anything and capped query length at roughly 8 KB. `sql query` now always `POST`s, with no length limit. Remove `--cache` from any script that passes it. **Workflows** Breaking changes * [`carto workflows share`](/carto-for-agents/cli/command-reference/workflows) and [`unshare`](/carto-for-agents/cli/command-reference/workflows) no longer accept `--user-id` or `--user-email`. Identify users with `--with <email>`, which is repeatable and comma-separated. This withdraws the `--user-id` / `--user-email` flags that `0.9.1` and `0.9.2` introduced. Any user with an email is still reachable; sharing by user ID alone is tracked as a separate request. Fix * [`carto workflows get`](/carto-for-agents/cli/command-reference/workflows), [`create`](/carto-for-agents/cli/command-reference/workflows), and [`update`](/carto-for-agents/cli/command-reference/workflows) now honor `--profile`. The flag was silently ignored on these three subcommands, so cross-org flows went out with the default profile's token and failed with a misleading "Permission denied". * [`carto workflows validate`](/carto-for-agents/cli/command-reference/workflows) now reports an edge whose `targetHandle` names an input the target node does not declare. Such an edge draws no connection line on the canvas even though the engine still runs it, so it previously surfaced only as a broken-looking DAG. **Maps** Fix * [`carto maps create`](/carto-for-agents/cli/command-reference/maps) and [`update`](/carto-for-agents/cli/command-reference/maps) no longer reject accessible Oracle (and other non-BigQuery) sources. The pre-create source probe used BigQuery-only SQL against every warehouse, so valid sources failed as false negatives. The probe now speaks each provider's dialect and surfaces the real warehouse error. New * [`carto maps validate`](/carto-for-agents/cli/command-reference/maps) rejects single-select Category SQL parameters that would load inconsistently in Builder. **Listing** Fix * [`carto workflows list`](/carto-for-agents/cli/command-reference/workflows) and [`carto maps list`](/carto-for-agents/cli/command-reference/maps) with `--order-by updatedAt` (or `createdAt`) no longer return HTTP 500. The camelCase forms the help advertises are now normalized before the request. **Imports** Fix * [`carto imports`](/carto-for-agents/cli/command-reference/imports) accepts files up to 5 GB, matching the server. A stale client-side guard had rejected anything over 1 GB. **Authentication** Fix * `--base-url` no longer requires the default profile's tenant to be reachable, so an override works even when that tenant is not. An empty `--token` now errors clearly instead of silently falling back to the stored profile. **Credentials** Improvement * [`carto credentials create token --apis`](/carto-for-agents/cli/command-reference/credentials) documents the `exports` scope, which [`carto export`](/carto-for-agents/cli/command-reference/export) requires. **Security** Improvement * The CLI writes `~/.carto/config.json` with owner-only (`0600`) permissions, and masks the `aiproxy` API key in command output. {% endupdate %} {% update date="2026-07-30" %} ## v0.9.2 **Users** New * [`carto users get`](/carto-for-agents/cli/command-reference/users) and [`carto users delete`](/carto-for-agents/cli/command-reference/users) now take an explicit `--user-id` or `--user-email` flag to say which user you mean, and `users delete` takes `--receiver-id` or `--receiver-email` for the user who inherits the content. Both commands used to infer the kind from the value and read anything containing an `@` as an email, so a user whose SSO ID contains one (`samlp|my-sso|jane@carto.com`) could not be targeted at all. See [Identifying a user](/carto-for-agents/cli/command-reference/users#identifying-a-user). **Workflows** New * [`carto workflows share`](/carto-for-agents/cli/command-reference/workflows) and [`unshare`](/carto-for-agents/cli/command-reference/workflows) accept `--user-id` alongside `--user-email`, both repeatable and comma-separated. Sharing with a user by ID was not possible before, so SSO users whose ID contains an `@` were out of reach here too. **All commands** Improvement * Flags accept the `--flag=value` form in addition to `--flag value`. This is the only way to pass a value that itself starts with `--`. {% endupdate %} {% update date="2026-06-29" %} ## v0.9.0 **Workflows** Breaking changes * [`carto workflows validate`](/carto-for-agents/cli/command-reference/workflows) now validates against the connection's **live component catalog** instead of running fully offline. On top of the structural checks, it confirms that every component name and parameter exists in the connection's catalog — native functions, extensions, and stored procedures. As a result it needs a connection (read from the bundle's `connectionId`, or supplied with the new `--connection <name|uuid>` flag) and an authenticated session. [`carto workflows create`](/carto-for-agents/cli/command-reference/workflows) and [`update`](/carto-for-agents/cli/command-reference/workflows) run the same catalog-aware pre-flight before submitting. {% hint style="warning" %} **Migration**: `workflows validate` previously made no API calls. If you run it in CI, make sure the bundle carries a `connectionId` (or pass `--connection`) and that the environment is authenticated. {% endhint %} **SQL** New * [`carto sql query`](/carto-for-agents/cli/command-reference/sql) and [`carto sql job`](/carto-for-agents/cli/command-reference/sql) accept `--param key=value` (repeatable) and `--params-json '<json>'` to bind query parameters. `--param` values are JSON-parsed — numbers, booleans, and arrays keep their type, everything else is treated as a string — while `--params-json` takes a full JSON object or array for complete control. The two flags can't be combined. * [`carto sql query`](/carto-for-agents/cli/command-reference/sql) also accepts a [named source](/carto-for-agents/cli/command-reference/named-sources) name in the SQL position, so you can run a saved query by name (and bind its parameters with `--param`) without writing the SQL by hand. **Admin** Fix * [`carto admin settings apply`](/carto-for-agents/cli/command-reference/admin) now reports any models the API failed to apply, so partial failures surface instead of appearing to succeed. {% endupdate %} {% update date="2026-05-29" %} ## v0.8.0 **Workflows** Breaking changes * [`carto workflows verify-remote`](/carto-for-agents/cli/command-reference/workflows) no longer fails on advisory warnings. The exit code (and the `valid` field on `--json` output) now reflects whether the workflow would be accepted by `workflows create`. Warnings are still listed in the output, but on their own they no longer break the run. {% hint style="warning" %} **Migration**: if you have a CI gate that relied on any warning failing the build, pass the new `--strict` flag to restore the previous behaviour. {% endhint %} New * [`carto workflows verify-remote --strict`](/carto-for-agents/cli/command-reference/workflows) restores the previous behaviour, where any warning fails the exit code. Useful for CI gates that want to enforce a clean run. Improvement * [`carto workflows components get --json`](/carto-for-agents/cli/command-reference/workflows) now returns the human-readable option labels alongside the values that components accept. For inputs like `native.isolines.mode`, bundle authors can pick the value the engine expects (`"walk"`) without mistaking it for the display label (`"Walk"`). * [`carto workflows create`](/carto-for-agents/cli/command-reference/workflows) accepts both a stringified `FeatureCollection` and a `FeatureCollection` object on the `native.tablefromgeojson` and `native.drawcustomgeographies` components, so workflows that ingest GeoJSON can now be authored from the CLI. Fix * [`carto workflows create`](/carto-for-agents/cli/command-reference/workflows) now prints the canonical workflow URL on success, so callers no longer have to assemble it themselves. **Maps** Improvement * [`carto maps schema layers`](/carto-for-agents/cli/command-reference/maps) now lists the four `Scale with zoom level` radius fields for tileset point layers — `radiusScaleWithZoom`, `radiusReferenceZoom`, `sizeMinPixels`, `sizeMaxPixels` — so bundle authors can discover the mode. [`carto maps validate`](/carto-for-agents/cli/command-reference/maps) also rejects two shapes that would silently break in Builder: `radiusScaleWithZoom: true` without a `radius` value, and `radiusScaleWithZoom: true` alongside a `radiusField`. Fix * [`carto maps create`](/carto-for-agents/cli/command-reference/maps) now emits the correct Builder URL. The URL could previously fall back to a different host that returned 404. **Connections** Fix * [`carto connections browse --max-items`](/carto-for-agents/cli/command-reference/connections) and `--max-children` are now honoured. Both flags were silently dropped, so browse output capped at 30 items regardless of value. **Credentials** New * [`carto credentials create token`](/carto-for-agents/cli/command-reference/credentials) accepts wildcard `--source` patterns (e.g. `"carto.shared.CARTO_*"`, or `"*"` for all sources on the connection), an `--expiration-date` flag (ISO date or shorthand like `30d` / `6m` / `1y`), and an optional `--name` label, so a single token can be scoped to a fleet of warehouses and aged out automatically. **Admin** New * [`carto admin settings get|apply|diff`](/carto-for-agents/cli/command-reference/admin) round-trips org-wide administrative settings (basemaps toggles, palettes, maps, connections, workflows, builder-gen-ai, carto-ai) as a single JSON bundle. Useful for moving settings between environments or capturing a snapshot for audit. {% endupdate %} {% update date="2026-05-14" %} ## v0.7.1 **Maps** Improvement * The `add_layer` core tool surfaced by [`carto maps agents core-tools`](/carto-for-agents/cli/command-reference/maps) now accepts `clickColumns` and `clickColumnsAggregation`, so the Builder AI agent can author click popups end-to-end (previously only hover popups were configurable). Aggregation rules mirror `hoverColumns` / `hoverColumnsAggregation`, and `clickColumns` has no field-count cap (the hover cap of 5 still applies). {% endupdate %} {% update date="2026-05-13" %} ## v0.7.0 This release introduces **map and workflow authoring from the command line** and lands alongside the new [CARTO for Agents](/carto-for-agents/carto-for-agents) section, which brings the CLI together with the [CARTO MCP Server](/carto-for-agents/mcp-server) and the [Agent Skills](/carto-for-agents/agent-skills) catalog. **Maps** New * Author Builder maps end-to-end from the CLI. [`carto maps create`](/carto-for-agents/cli/command-reference/maps) and [`carto maps update`](/carto-for-agents/cli/command-reference/maps) accept a round-trippable JSON bundle as a positional argument, a filesystem path, or via stdin. The bundle returned by `maps get --json` can be piped straight back into `create` or `update`. * New commands round out the authoring loop: [`maps validate`](/carto-for-agents/cli/command-reference/maps) (offline pre-flight, no API calls), [`maps verify-remote`](/carto-for-agents/cli/command-reference/maps) (pre-flight plus warehouse-side dry-runs), [`maps publish`](/carto-for-agents/cli/command-reference/maps) (freeze a snapshot so shared and public viewers see the current state), [`maps schema`](/carto-for-agents/cli/command-reference/maps) (JSON Schema reference for bundle authors), [`maps agents`](/carto-for-agents/cli/command-reference/maps) (inspect the AI surface available on a tenant), and [`maps copy --dest-profile`](/carto-for-agents/cli/command-reference/maps) (duplicate a map across organizations). * `maps create` and `maps update` responses now expose `builderUrl`, `viewerUrl`, and `publicUrl` as first-class fields. Improvement * Bundles are pre-flight validated before any API call, with clear pointers to the offending field on failure. Broken sources, missing required fields, and shapes that would render incorrectly in Builder are rejected locally. * Sensible defaults are auto-filled when bundle fields are omitted (popup `enabled`, widget `operationColumn`, `collapsible`, basemap and viewport hydration from `/stats`), so smaller bundles "just work". **Workflows** New * Author and validate workflows from the CLI. [`carto workflows create`](/carto-for-agents/cli/command-reference/workflows), [`update`](/carto-for-agents/cli/command-reference/workflows), and [`validate`](/carto-for-agents/cli/command-reference/workflows) (offline schema check), plus the new [`workflows verify`](/carto-for-agents/cli/command-reference/workflows) command — warehouse-aware validation that requires `--connection <name|uuid>` and runs the full structural, engine-compile, schema-trace, and sources stack without writing the workflow. * [`carto workflows components list`](/carto-for-agents/cli/command-reference/workflows) and [`get`](/carto-for-agents/cli/command-reference/workflows) surface the agent-facing component catalog. Both require `--connection <name|uuid>` so extension and stored-procedure components appear alongside native ones. Fix * `carto workflows list --order-by updated|created` no longer fails with a 500. The CLI now aliases `updated` → `updated_at` and `created` → `created_at` before calling the API. Canonical values still work unchanged. {% hint style="info" %} For end-to-end recipes — including the agent skills that drive these flows — see the [`carto-create-builder-maps`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-builder-maps) and [`carto-create-workflow`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-workflow) skills in the [agent-skills repository](https://github.com/CartoDB/agent-skills), and the [CARTO for Agents](/carto-for-agents/carto-for-agents) section. {% endhint %} {% endupdate %} {% update date="2026-04-27" %} ## v0.6.0 Breaking changes * [`carto export`](/carto-for-agents/cli/command-reference/export) no longer accepts `--query`. Use `--select <cols>` (comma-separated column list) and `--where <predicate>` (warehouse-native SQL, no leading `WHERE`) instead. `--limit` is unchanged. {% hint style="warning" %} **Migration**: rewrite `carto export --query "SELECT a, b FROM t WHERE c > 0"` as `carto export <t> --select a,b --where "c > 0"`. {% endhint %} {% endupdate %} {% update date="2026-04-25" %} ## v0.5.0 Fix * Kebab-case flag forms (`--page-size`, `--order-by`, `--order-direction`, `--max-children`) on list commands now work as documented across `maps`, `workflows`, `connections`, `users`, `credentials`, and `admin`. The camelCase forms (`--pageSize`, `--orderBy`, …) continue to work as aliases. {% endupdate %} {% update date="2025-12-31" %} ## v0.1.0 New * Initial release of the CARTO CLI. * Multi-profile authentication, including M2M OAuth for CI/CD pipelines. * Commands for `maps`, `workflows`, `connections`, `credentials`, `users`, `imports`, and `admin`, with JSON output mode for scripting. {% endupdate %} {% endupdates %} # Overview The CARTO Workspace is the user interface for our next generation cloud-native Location Intelligence platform. It allows you to create stunning maps and perform spatial analytics at scale, with everything running directly on top of your cloud data warehouse(s). Learn how to make the most out of our Builder tool, Analytics Toolbox, Data Observatory, and other new features. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-186e451eaa60c7924ab04a921acd4bd223b19306%2FScreenshot%202023-01-12%20at%2018.25.14.png?alt=media" alt="Screenshot of the CARTO Workspace showing onboarding materials"><figcaption></figcaption></figure> Check out the following pages for setting up your organization, getting acclimated to the workspace, and creating your first map: * [CARTO Workspace overview](/carto-user-manual/overview/carto-workspace-overview) * [Creating your first map](/getting-started/quickstart-guides/creating-your-first-map) # Creating your CARTO organization In this guide, we'll walk through the process of creating your first CARTO organization. This will be the first step to start creating stunning maps and perform spatial analytics at scale, with everything running directly on top of your cloud data warehouse. 1. **Account sign up** * Go to the [CARTO Sign up](http://app.carto.com/signup) page. * Enter your email address and password. You can also sign up with your existing Google account by clicking *Continue with Google*. * Follow the steps to verify your email and continue with your new organization setup. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-dd623bd35ad32f25959b15d7908689b7f29b6b6b%2FScreenshot%202024-04-02%20at%2017.57.18.png?alt=media" alt=""><figcaption></figcaption></figure> 2. **Organization setup** If your email domain is already associated with an existing CARTO organization, you will be able to join (or request to join) any of the existing organizations associated with that domain. Alternatively, you will be able to create a brand new organization. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-afd03de680c6593dfe879a57ff9806bef4e7cd29%2FScreenshot%202024-04-02%20at%2018.25.19.png?alt=media" alt=""><figcaption></figcaption></figure> For new organizations, you will need to choose an organization name (e.g. CARTO) and a **deployment region**. As a rule of thumb, you should choose the region closest to your data warehouse. For more information, check our article on [deployment regions](/carto-user-manual/overview/carto-cloud-regions). After finishing the form, click "Let's get started with CARTO!" to complete the sign up process and get access to the CARTO Workspace. By signing up you accept the [Terms and conditions of the Services](https://carto.com/legal/) and the [privacy notice](https://carto.com/privacy/). You are ready to start using CARTO! # CARTO Cloud Regions For new CARTO [**cloud deployments**](/faqs/deployment-options), users can choose between four different regions. These correspond to four separate CARTO tenants, each located in a different geographical location: * United States East * Europe West (located in the EU) * Asia Northeast (located in Japan) * Australia Southeast <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-17f8fa00090186b03895b6c548b51efdb723a898%2FScreenshot%202024-04-12%20at%2012.45.12.png?alt=media" alt=""><figcaption></figcaption></figure> These tenants are fully managed CARTO deployments that we host on our own cloud (on the Google Cloud Platform). We manage configuration, updates, and versioning. Changes to CARTO are pushed simultaneously to these four tenants, so they are functionally equivalent. All your organization’s data such as maps, workflows, applications, etc; will be stored in the selected region. In addition, the [CARTO Data Warehouse](/carto-user-manual/connections/carto-data-warehouse) of your organization will be located in that region as well. ### Choosing a region There are a two main considerations when choosing a region: * Proximity to your data * Compliance and data regulations Ideally, you should choose the region that is closest to your data to reduce latency and improve performance. For example, if you’re planning to connect CARTO to your Google BigQuery or Snowflake data in any US region, we recommend you choose the CARTO US region for optimal performance. Some organizations might also have to choose a region that complies with specific data protection and privacy regulations, such as GDPR in the EU. For additional help, you can use [**Google Cloud's Region Picker**](https://googlecloudplatform.github.io/region-picker/) to help you select a cloud region. ### Checking my organization's region The region of your organization is visible from the admin panel in the [Organization Settings](/carto-user-manual/settings). <figure><img src="https://lh7-us.googleusercontent.com/2V5JeQ-3svQAJmb1d-hsLuu8tAJL4m1c36rJ5WygAi6PBSsbQ5qn4ZP9yTUOI6PnVjNSXL6WY6Zfa7CTfovApOgkwpny9QWoUzFAu1suTQdwf1JOBqI0OBL59FAPdluAJPhH8klnbFosO4TW8vpCEFU" alt=""><figcaption></figcaption></figure> If you're not an admin, you can still check your organization's region by looking at the URL: * *clausa* stands for United States East * *pinea* for Europe West * *thunbergii* for Asia Northeast * *radiata* for Australia Southeast\ \ \\ # CARTO Workspace overview Learn everything you need to know about your Workspace and how to make the most out of it. When you log in to your CARTO user account, you will be presented with your Workspace. The Workspace allows you to access all components of the CARTO platform via a single interface. It will allow you to manage connections to your data warehouse(s), explore your data, subscribe to Data Observatory datasets, develop spatial applications, and run visualizations and spatial analysis through our tools Builder and Workflows. ## **Homepage** The first time that you access the Workspace, you will see a *Welcome* banner with links providing quick access to different actions to get you started with CARTO, like creating your first connection or your first map and workflow, or starting with your spatial analysis in an easy guided way from our editable pre-built demo maps and demo workflows. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-5bdcf8f0edfff2af8f678a95697e0a90731a4199%2FScreenshot%202024-07-05%20at%2012.58.20.png?alt=media" alt=""><figcaption></figcaption></figure> From the **“Connect your data warehouse”** banner, you can easily connect your data warehouse(s) to start using CARTO by clicking on *Create new connection* button. Check the quick guides to [connect data](/getting-started/quickstart-guides/connecting-to-your-data) and [creating your first map](/getting-started/quickstart-guides/creating-your-first-map) to get started. After creating your connection, you can also **upload local files** right from the homepage by clicking on *Import your data* button. Check this [guide](/carto-user-manual/data-explorer/importing-data) to start importing your data into your data warehouse. From the **“What's new”** section, you will find announcements of new features, interesting articles, and the latest news related to CARTO from our blog. Stay tuned and don’t miss out on the latest news! <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-7b8336c0d878403ed607ce96dc2152123333a915%2FScreenshot%202024-07-05%20at%2012.59.34.png?alt=media" alt=""><figcaption></figcaption></figure> ## **Getting started** In this section you have a checklist with five quick steps to guide you to the different content pieces to help you get started with CARTO. Once you have completed all the steps, it will be marked as completed and you can close the panel by clicking on *Close*. If you want to skip the steps, just click on *I´m ready, skip onboarding* to close the panel. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-4a8a97ba18e5a07f0e18161a0067aa953a5f8c17%2FCaptura%20de%20pantalla%202023-09-08%20a%20las%2012.14.24.png?alt=media" alt="" width="375"><figcaption></figcaption></figure> ## **Help sidebar** The help sidebar is always available, including when you're creating Maps and Workflows. It contains: * An **AI-powered search bar**, similar to the one you can use in this documentation. Ask anything about CARTO and get quick answers, pointing in the right direction and including a link to this documentation. * Relevant links to our [What's new](/whats-new) section, the [CARTO Academy](https://academy.carto.com), and the [CARTO Support ](/faqs/support-packages)team. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-d1bfabd8d46346a979e8d94981e541ed40abc494%2FScreenshot%202024-04-11%20at%2013.39.48.png?alt=media" alt=""><figcaption></figcaption></figure> ## **Recent projects** View your latest [projects](/carto-user-manual/projects). This module displays the projects you have worked on most recently, so you can jump straight back into them, and shows how many items each one holds. Click *View all* to open the full Projects section. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-2dbe3f8e0ff94cf361968fb795413546fae08de3%2Frecent-projects.png?alt=media" alt=""><figcaption></figcaption></figure> ## **Recent maps** View your latest content. This module displays the latest maps that you have been working on, so that you can quickly access and continue working on them. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-ca584298cef102eee1b50e98d678e468d56c226f%2Frecent_maps.png?alt=media&token=b17b0494-fde2-4865-839b-a3e25c79d474" alt=""><figcaption></figcaption></figure> If you are the owner of the map, you will have access to the quick actions menu to manage your map by clicking on the three dot icon of the map card. There are 4 options available: Edit map properties, [Share](/carto-user-manual/maps/sharing-and-collaboration), [Duplicating maps](/carto-user-manual/maps/managing-maps#duplicating-maps) and [Delete](/carto-user-manual/maps/managing-maps#deleting-maps). <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-016c8cc1fef346ce7a36944eb7f397bfb3bb92a7%2Fimage.png?alt=media" alt="" width="337"><figcaption></figcaption></figure> ## **Recent workflows** View your latest accessed workflows. This module displays the latest workflows that you have been working on, so that you can quickly access and continue working on them. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-c2a235229e65d3fbe33eb158408be26577615fdf%2FCaptura%20de%20pantalla%202023-09-08%20a%20las%2012.22.47.png?alt=media" alt=""><figcaption></figcaption></figure> ## **Recent datasets** View your latest datasets for easy access. This module displays the latest datasets that you have been working on, so that you can quickly access and continue working on them. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-2613a242e56c54f7c96b906310127236b0cac5ac%2Frecent_datasets_new.png?alt=media&token=7e68a75f-83a1-4953-a9c2-769e74cd3ba1" alt=""><figcaption></figcaption></figure> ## **Navigation Menu** In the left panel, you can find the *Navigation Menu* with all the available options to access the CARTO components: Home, Maps, Data Explorer, Data Observatory, Connections, Settings, and Developers. In the bottom part of the menu, you have additional options to join the “CARTO Users” Slack channel, send us direct product feedback, or access the Documentation portal. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-7bd9d99b82cd59e4b907ea2c34f79c6ea2f1ac18%2Fthe_menu_sections.png?alt=media&token=1ed47894-d9ea-4798-ab7c-8dc651b9fa7b" alt=""><figcaption></figcaption></figure> # Projects Organize your maps and workflows into projects and folders, and manage sharing for everything inside from a single place. Projects and folders let you organize your maps and workflows into a clear structure instead of a single flat list. A **project** is a top-level container, and a **folder** lives inside a project or another folder. With them you can: * **Move maps and workflows into them** to keep related work together. * **Manage sharing from the top.** Share a project or folder once and everything inside it inherits that access, so you set permissions in one place instead of item by item. * **Add shortcuts** for maps or workflows that need to live in more than one place, or for assets you do not own. Organize your work however suits you, and nest folders as deep as you need. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-b46ea9e42edd84dcc1475750c14255a8244fec23%2Fprojects-list.png?alt=media" alt=""><figcaption>The Projects section, with a New project button and one card per project</figcaption></figure> ## Creating projects and folders Projects live in the **Projects** section of the Workspace. Click **New project** and give it a name. Open the project and use the new-folder button to add folders inside it, nesting them as deep as you need. To start something new right where it belongs, use **New asset** to create a map, workflow, or AI Agent (or a workflow from a template) directly inside a project or folder. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-cd71a01755dc7c599ebf7652ac7be6deff2ba9b0%2Fproject-new-folder.png?alt=media" alt=""><figcaption>Creating a folder inside a project</figcaption></figure> ## Organizing your maps and workflows To bring existing work into a project or folder, move it in. In the Maps or Workflows section, open the three-dot menu on the card and select **Move to**. Pick a destination by switching between your own and others' projects, following the breadcrumb, and drilling into folders; you can also create a new project or folder without leaving the modal. Confirm with **Move here**. The map or workflow now lives in that project or folder and takes on its sharing (see [Sharing projects and folders](#sharing-projects-and-folders)). It lives in one project or folder at a time, and only maps, workflows, folders, and shortcuts can live inside one, so connections, datasets, and other resources stay in their own sections. The same **Move to** flow relocates a map or workflow between projects and folders, and **Remove from project** (or **Remove from folder**) takes it back out. Moving or removing only changes where a map or workflow lives and the sharing it inherits; it never deletes the map or workflow itself. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-16f7fe4b7fe5affdb7398fe117a3d55cc43dce38%2Fmove-map-to-project.png?alt=media" alt=""><figcaption>The Move to modal, where you pick the destination project or folder</figcaption></figure> {% hint style="info" %} Wherever a map or workflow lives, it is always accessible from the **Maps** and **Workflows** sections of your Workspace. Projects and folders organize your content, they do not hide it from those lists. {% endhint %} ### Shortcuts Moving is the usual way to place a map or workflow. When the same one needs to appear in more than one place, or you want to reference an asset you do not own, add a **shortcut** instead. Open the three-dot menu on the card and select **Create shortcut**. A shortcut is just a pointer: it does not move the original or make a copy. Shortcuts inherit nothing. The map or workflow a shortcut points to keeps its own sharing, and a shortcut placed inside a shared project does not grant anyone access to it. Deleting a shortcut removes only the pointer, never the original. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-7f2f40cfabdae3c0b5dc34c283c11c50e61fa31f%2Fproject-contents.png?alt=media" alt=""><figcaption>A project holding a folder and a map</figcaption></figure> ## Sharing projects and folders You share a project or folder the same way you share a single map or workflow: pick a mode (Restricted or Organization) and add the users or groups who should have access. Only the owner can change how a project or folder is shared. See [Sharing and collaboration](/carto-user-manual/maps/sharing-and-collaboration) for maps and [Sharing workflows](/carto-user-manual/workflows/sharing-workflows) for workflows. When you share a project or folder, everything inside inherits that access, so you set permissions once instead of item by item. Sharing a project covers its folders, maps, and workflows; sharing a folder covers everything in that folder. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-436bc395a3601b1fe46c6e1021c154764d89657d%2Fproject-share.png?alt=media" alt=""><figcaption>Sharing a project. Lower-level folders and content inherit these settings</figcaption></figure> Inheritance is **additive**: a map or workflow keeps its own sharing and gains whatever it inherits from the project or folder above it. A map shared with person X that you move into a folder shared with team Y ends up accessible to both X and Y. In the map or workflow's own Share modal, inherited access is labeled **Access is inherited from an upper level**, so you can tell it apart from access set directly on the asset, and you can still add more people or groups on top. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-372959788cf58a2376e8302993c8084991cfd19f%2Fshare-access-inherited.png?alt=media" alt=""><figcaption>On a map, access inherited from a parent project or folder is labeled in the Share modal</figcaption></figure> {% hint style="warning" %} **Shortcuts do not inherit sharing.** A shortcut inside a shared project stays a pointer. The map or workflow it points to keeps its own sharing settings, so someone who can open the project will only be able to open the target through the shortcut if that map or workflow has been shared with them directly. {% endhint %} {% hint style="info" %} Projects and folders can only be Restricted or Organization; they cannot be made public. A map inside a project can still be shared publicly on its own, unless an admin has disabled public map sharing from the [Governance](/carto-user-manual/settings/organization-governance) settings. {% endhint %} ## Managing projects and folders From the three-dot menu on a project or folder card, or the header when you are inside it, you can rename it, share it, move a folder into another project or folder, and delete it. Like the Maps and Workflows sections, the Projects section can be shown as a grid or a list, and you can search, sort, and filter by owner. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-bd85feae2da6826fca1b9efd5fc12077730cf653%2Fproject-card-menu.png?alt=media" alt=""><figcaption>The project card menu: rename, share, or delete</figcaption></figure> {% hint style="info" %} **Deleting a project or folder never deletes the maps and workflows inside it.** They stay available from the Maps and Workflows sections and only lose the sharing they inherited from that project or folder. To delete a map or workflow, do it explicitly from its own card. {% endhint %} ## Managing projects from the CLI Projects and folders can also be created, browsed, and reorganized programmatically with the CARTO CLI. See the [`projects` command reference](/carto-for-agents/cli/command-reference/projects). # Maps The CARTO Workspace includes functionalities for creating and publishing maps in a simple manner, using the CARTO map tool: Builder. Builder is designed to allow technical and non-technical audiences to visualize, explore, and filter large amount of location data in your browser. This guide will teach you how to create a map in the CARTO Builder, and perform data analysis by adding data to a map, adding filters, and more. In the Maps section of the Workspace, you will see the list of your current maps. If you haven’t created a map yet, you will see the following page: <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-056dd14c18a2cf2291f0a04912b307cdf5a3c860%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> To create a new map, click *Create your first map*. This will open the CARTO map tool: Builder. CARTO Builder contains many features that guide you through the process of creating a map, changing the styling, and selecting how your data appears. Use the following task list as guide for some of the main CARTO Builder features: * Add your data [guide](/carto-user-manual/maps/data-sources#adding-a-data-source) * Style your maps [guide](/carto-user-manual/maps/layers) * Set widgets [guide](/carto-user-manual/maps/widgets) * Customize your map views [guide](/carto-user-manual/maps/map-view-modes) * Add SQL parameters [guide](/carto-user-manual/maps/sql-parameters) * Apply a mask to your map and filter out your data [guide](/carto-user-manual/maps/feature-selection-tool) * Publish and share your maps [guide](/carto-user-manual/maps/sharing-and-collaboration) # Map layout Every Builder map has a few dedicated areas, so you and your viewers always know where to find things: * **Widgets panel** on the right, with the map's widgets and description. * **Parameters bar** above the map, when the map has SQL parameters. * **Map toolbar** at the top left of the map, with the map tools. * **Map controls** in the bottom-right corner, with zoom, basemap and 3D. * **Legend** in the bottom-left corner. As an Editor, you choose how the widgets panel looks, and your choice is saved with the map. Viewers, guests and anyone with a public link see the map exactly as you set it up. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-4ca452d89894c10f5be532030c1ac52648b1c6e8%2Fbuilder-layout-tour.gif?alt=media" alt="A tour of the Builder layout"><figcaption>A tour of the Builder layout</figcaption></figure> ## Widgets panel The widgets panel shows your [widgets](/carto-user-manual/maps/widgets) and the [map description](/carto-user-manual/maps/map-description). Use the buttons in the top-right corner of the map to show or hide them. ### Layout options As an Editor, click the **Layout** button in the map toolbar to choose how the widgets panel appears: * **Columns:** show widgets in **1 column** or **2 columns** side by side. * **Floating:** turn it on to show the panel as a card over the map, so the map uses the full width. Turn it off to dock the panel next to the map. * **Dual map view:** split the map in two to compare them. Learn more in [Map view modes](/carto-user-manual/maps/map-view-modes). * **Reset layout:** goes back to the default layout, with one docked column. It also turns off dual map view and returns full-width widgets to column width. It appears once you change something. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-ab57e022603c4c0737b9323e0a2dbfb74dd97096%2Fbuilder-layout-popover.png?alt=media" alt="The Layout options"><figcaption>The Layout options</figcaption></figure> <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-c6ef4bf065e1b6180a66e7b20baa6b3a17a0598b%2Fbuilder-layout-floating-single-widget.png?alt=media" alt="A single widget floating over the map"><figcaption>A single widget floating over the map</figcaption></figure> By default, the widgets panel is docked with one column. Layout changes appear in the map's [version history](/carto-user-manual/maps/version-history), so you can go back to an earlier layout. {% hint style="info" %} You can't float the widgets panel while dual map view is on. Turning on dual map view docks the panel, and it floats again on its own when you turn dual map view off. {% endhint %} ### Full width widgets With two columns, you can give a widget the full width of the panel, for example to make a key number stand out on its own row. Open the widget's more options menu and choose **Full width**. Choose **Column width** to put it back in a single column. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-ebb4b25c339215fba3b4f3e0a4781c5c69585847%2Fbuilder-widget-full-width-menu.png?alt=media" alt="The Full width option in a widget's more options menu"><figcaption>The Full width option in a widget's more options menu</figcaption></figure> <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-23a637d8d8699330196fa442c2c9fafb209d3a5f%2Fbuilder-widget-full-width-result.png?alt=media" alt="A formula widget taking the full first row"><figcaption>A formula widget taking the full first row</figcaption></figure> If a widget ends up alone in a row, it fills the whole row, so there are no empty gaps. ### Collapsing widgets Anyone viewing the map can collapse a widget from its header to hide it. With two columns, the two widgets in a row collapse and expand together. Widgets can also collapse automatically. In the widget's Behavior settings, turn on **Collapse when no layers are visible**. The widget stays in the panel, collapsed to its header, until one of its layers is visible again. Widgets at the bottom of the map, such as the Table widget, have their own collapse control. You can keep them open while the widgets panel is hidden. ## Parameters bar When a map has [SQL parameters](/carto-user-manual/maps/sql-parameters), they appear in a bar above the map. Each one shows its name and current value, so it's clear at a glance what the map is showing. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-0c102c531995c78ee06ae06b3bfb226ace5fd14f%2Fbuilder-layout-parameters-bar.png?alt=media" alt="The parameters bar, with a Text parameter open"><figcaption>The parameters bar, with a Text parameter open</figcaption></figure> * **Reorder parameters:** as an Editor, drag a parameter by its handle to a new position. Put the most useful ones first, since they stay visible when the bar is full. * **When the bar is full:** use the arrows at the edges of the bar to see the rest. The bar only appears when the map has parameters. As an Editor, you can also hide parameter controls from viewers in [Map settings for viewers](/carto-user-manual/maps/sql-parameters/publishing-sql-parameters). ## Map toolbar The map tools are grouped in one toolbar at the top left of the map: * [Feature selection tool](/carto-user-manual/maps/feature-selection-tool) * [Measure distances](/carto-user-manual/maps/measure-distances) * [Comments](/carto-user-manual/maps/sharing-and-collaboration/comments) * [Search locations](/carto-user-manual/maps/search-locations) Editors also see the **Layout** button. Viewers see the tools you turn on in [Map settings for viewers](/carto-user-manual/maps/sharing-and-collaboration/map-settings-for-viewers), plus a button to chat with the map's [AI Agent](/carto-user-manual/ai-agents) when it has one. ## Map controls and legend Zoom, your location and the [basemap selector](/carto-user-manual/maps/basemaps/basemap-selector) are grouped in the bottom-right corner of the map. As an Editor, you'll find the 3D toggle in the basemap selector. Learn more in [Map view modes](/carto-user-manual/maps/map-view-modes). The [legend](/carto-user-manual/maps/legend) is in the bottom-left corner. Click the layers button to open it. ## Hiding the left panel As an Editor, press **Ctrl + B** (**⌘ + B** on Mac) to hide the Layers and Sources panel and give its space to the map. Press it again to bring the panel back on the tab you were using. ## Tablets and phones Maps adapt to tablets, phones and narrow embeds, keeping the map front and center. On these screens you can view and explore maps. To edit a map, use a computer. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-b71fb8fbab98b5fd425c802ce8038334ec717fa8%2Fbuilder-responsive-layout.gif?alt=media" alt="A map adapting from desktop to tablet to phone"><figcaption>A map adapting from desktop to tablet to phone</figcaption></figure> * **Tablets:** the widgets panel keeps the docked or floating layout you chose, in one column. * **Phones:** widgets and the map description open full width over the map. With dual map view, the two maps are shown one above the other. * **AI Agents:** viewers can chat with the map's [AI Agent](/carto-user-manual/ai-agents) on tablets and phones too. On a phone, the agent opens full screen with its conversation starters. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-59ebc628a1c5453f795c2691b5284cbdc111d29e%2Fbuilder-tablet-layout.png?alt=media" alt="A map on a tablet"><figcaption>A map on a tablet</figcaption></figure> <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-1712e812d123ad7e1feffd249777c457219a866b%2Fbuilder-phone-widgets-and-agent.png?alt=media" alt="A map on a phone, with the widgets and the AI Agent"><figcaption>A map on a phone, with the widgets and the AI Agent</figcaption></figure> Editing options, such as the Layers and Sources panel and widget settings, aren't shown on these screens. A notice explains this the first time you open a map, and you can choose **Do not show again**. # Data sources CARTO Builder allows you to add sources by connecting directly with your data warehouses, ensuring security and data governance. Once a source is added, the related layer associated with the source is also rendered on the map. From this point, you can start styling your layer, adding widgets, and creating your interactive application. ## Data sources types Builder currently support the following data sources types: * [**Simple features**](/carto-user-manual/maps/data-sources/simple-features): Unaggregated features using standard geometry (point, line or polygon) and attributes, ready to use in Builder. * [**Spatial Indexes**](/carto-user-manual/maps/data-sources/spatial-indexes): Aggregated data sources for improved performance or specific use cases, including Quadbin and H3 spatial indexes. * [**Pre-generated tilesets**](/carto-user-manual/maps/data-sources/pre-generated-tilesets)**:** Tilesets pre-generated using CARTO Analytics Toolbox procedures or Workflows and stored directly in your data warehouse, ideal for handling very large, static datasets. * [**Raster**](/carto-user-manual/maps/data-sources/rasters): A raster source is composed of grids of pixels, where each pixel contains a value representing specific information * **Sources without an associated layer**: These are data sources added to a map that has not associated layer. They are typically used to power widgets, SQL parameters, or AI Agents**,** enabling advanced interactivity and insights without visual clutter. You can add a layer from these sources at any time. ## Methods for adding sources In Builder, you can add data sources either as table sources by connecting to a materialized table in your data warehouse or through custom SQL queries. These queries execute directly in your data warehouse, fetching the necessary properties for your map. * **Table sources:** Connect directly to your data warehouse table through the data explorer dialog. Once connected, the data source is added including its related layer. * **SQL query sources:** Perform a custom SQL query that will act as your input source. Once you execute it, if valid, a new data source and its linked layer will be added to the Builder. {% hint style="info" %} **Best practices for SQL Query sources** SQL Editor is not designed for **conducting complex analysis** or detailed step-by-step geospatial analytics directly, as Builder executes a separate query for each map tiles. For analysis requiring high computational power, we recommend two approaches: * **Materialization**: Consider materializing the output result of your analysis. This involves saving the query result as a table in your data warehouse and use that output table as the data source in Builder. * **Workflows**: Use [CARTO Workflows](/carto-user-manual/workflows) for conducting step-by-step analysis. This allows you to process the data in stages and visualize the output results in Builder effectively. {% endhint %} ## Adding data sources To add sources in Builder, click on "Add source from" and choose from the following options: * [**Data Explorer**](#adding-a-source-from-data-explorer)**:** Browse and add tables as sources from your existing connections. * [**Custom Query (SQL):**](#adding-a-source-from-a-custom-query-sql) Write your own SQL query using the connection of your choice. * [**Import file**](#adding-source-by-importing-a-file)**:** Start the process of importing a file to a CARTO connection. You can also **drag and drop** your files directly on Builder to start the import flow. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-176da1013d8949c38eeba9c00baab2335b8f0dae%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> {% hint style="info" %} [Partitioned BigQuery tables](https://cloud.google.com/bigquery/docs/partitioned-tables) require a WHERE clause in the query filtering by the column used for the partition. If you need to load a BigQuery partitioned table in Builder, add it as a SQL Query source like: ```sql SELECT * FROM project.dataset.my_partitioned_table WHERE partition_column = 'value' ``` {% endhint %} ### **Adding a source from Data Explorer** To add a source, navigate to the desired location, select your table and click 'Add Source'. The source and its associated layer will be added to the map. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-e67c6a1147be030f1d39d304376171649ed306d6%2FScreenshot%202025-11-06%20at%2014.11.35.png?alt=media" alt=""><figcaption></figcaption></figure> {% hint style="success" %} You can star connections, database/projects/schemas and tables to quickly access them later. For more information, see [Starring items for quick access](/carto-user-manual/data-explorer#starring-items-for-quick-access). {% endhint %} ### **Adding a source from a Custom Query (SQL)** Use the SQL Editor panel in Biulder to add a source by selecting a specific connection. Create your own SQL queries to perform simple analysis, create WHERE statements to pre-filter your data, or use SQL Parameters. You can also leverage CARTO Analytics Toolbox directly from this interface. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-857a7daa5e32f2fb0b2e32e24f6fee84557089e3%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> ### **Adding source by importing a file** CARTO allows creating tables in your connections by importing files from your computer or via URL. Once a file is imported, the resulting table can be previewed in Data Explorer and used in Builder and external applications. {% hint style="success" %} You can also **drag and drop** files directly on Builder to start the import flow. {% endhint %} <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-6616b32f18fd9ffa7282ebbac8f9e5b2dc445cca%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> {% hint style="info" %} Find more information about compatible data warehouses, supported formats, column names, and delimiters in our [Importing Data](/carto-user-manual/data-explorer/importing-data) documentation. {% endhint %} # Simple features Builder supports simple features stored as geometry or geography in cloud data warehouses. These simple features are defined as a standard which specifies digital storage of geographical data, usually point, line or polygon, storing both spatial and non-spatial features. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-f5ca8788bbd30878af125e427ba666e1dbde7e29%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> ## Supported spatial column types CARTO identifies the geo column of a source from the column type reported by the data warehouse. This table shows the type of simple features (`geography` or `geometry`) supported on each data warehouse: | | **Geography** | **Geometry** | | ------------------------ | ------------- | ------------- | | **BigQuery** | ✅ | Not Supported | | **CARTO Data Warehouse** | ✅ | Not Supported | | **Snowflake** | ✅ | Not Supported | | **Databricks** | Not Supported | ✅ | | **Amazon Redshift** | Not Supported | ✅ | | **PostgreSQL** | Not Supported | ✅ | | **Oracle** | Not Supported | ✅ | Geometries stored in **text columns** (WKT, GeoJSON) or in **generic binary columns** (WKB in a `BYTES`, `BINARY`, `VARBYTE` or `BYTEA` column) are not detected as geo columns. Cast them to the spatial type of your data warehouse in the SQL Query of your source, or materialize a table with a proper spatial column. {% hint style="info" %} **Converting between geography and geometry** If your column uses the type that is not supported by your provider, you can convert it: * **Snowflake:** convert `GEOMETRY` to `GEOGRAPHY`, for example with the [Geometry to Geography](/carto-user-manual/workflows/components/data-preparation#geometry-to-geography) component in Workflows. * **Amazon Redshift** and **PostgreSQL:** convert `GEOGRAPHY` to `GEOMETRY`, for example with the [Geography to Geometry](/carto-user-manual/workflows/components/data-preparation#geography-to-geometry) component in Workflows. {% endhint %} ### Coordinate reference systems | | **Projection support** | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **BigQuery**, **CARTO Data Warehouse**, **Snowflake** | `GEOGRAPHY` values are always WGS84 (`EPSG:4326`). Nothing to configure. | | **Databricks** | Coordinates are expected to be WGS84 (`EPSG:4326`) longitude/latitude. CARTO does not reproject Databricks geometries, so data in another projection will not display correctly. | | **PostgreSQL**, **Amazon Redshift**, **Oracle** | Any SRID is supported as long as it is set on the geometries. CARTO reads the SRID from the data and reprojects on the fly when needed. If the SRID is unset (`0`), WGS84 is assumed. | Reprojecting on every tile request has a cost. For the best performance, store your geometries in the projection recommended for each data warehouse and make sure the SRID is set — check the [performance considerations](/carto-user-manual/maps/performance-considerations) section for details. ## Limitations {% hint style="info" %} When working with simple features in Builder, ensure that your spatial column contains only a single type of geometry—either points, lines, or polygons. Mixing different geometry types within the same spatial column is not supported. To handle multiple geometry types, use separate sources for each type. The single-part and multi-part variants of the same family can be mixed: `POINT`/`MULTIPOINT` are both rendered as points, `LINESTRING`/`MULTILINESTRING` as lines, and `POLYGON`/`MULTIPOLYGON` as polygons. {% endhint %} {% hint style="warning" %} **GEOMETRYCOLLECTION is not supported** If your data contains GEOMETRYCOLLECTION geometry types, you'll need to convert them to individual geometry components before visualization. Use the ST\_Dump function in your SQL query to explode geometry collections. {% endhint %} {% hint style="warning" %} **Provider-specific limitations** * **Oracle:** only two-dimensional `SDO_GEOMETRY` values are supported (`SDO_GTYPE` `2001`, `2002`, `2003` and `2007`). Geometries with a Z or M dimension are not supported. * **Databricks:** native `GEOMETRY` and `GEOGRAPHY` types require Databricks Runtime 17.1 or above (Spark 4.0.0), which is a [requirement for creating a Databricks connection](/carto-user-manual/connections/databricks#setup-requirements). Legacy Databricks connections instead store geometries as WKB in binary columns and need the [Prepare for Visualization](/carto-user-manual/workflows/components/spatial-operations#prepare-for-visualization) component before they can be visualized. {% endhint %} ## Visualizing simple features Builder ensures performance experience when rendering simple features on a map as data is loaded progressively via vector tiles. The data for these tiles is extracted by pushing down SQL queries to the data warehouse, and they are requested as you zoom in and out or pan the map. Note these queries in Builder are cached. To understand more how caching works and different methods to keep your data fleshed, check this link in our [documentation](/carto-user-manual/maps/data-sources/managing-data-freshness). Find more information about performance consideration for this data source type in [this section](/carto-user-manual/maps/performance-considerations). # Spatial Indexes The CARTO platform natively supports spatial indexes, enabling you to leverage their capabilities when working with large-scale data directly in your data warehouse. Spatial indexes are excellent for large-scale analytics and visualization. Using Builder, you can create stunning and powerful visualizations by connecting directly to these types of sources. The supported spatial index formats are quadbins and H3. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-b9e3c7be9a6a2c6ecee0a9751fee5797aa76858d%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> Based on Discrete Global Grid (DGG) systems, spatial indexes reference each cell of the grid. Think of a spatial index as an id that always makes reference to the same portion of the surface on Earth. * This portion of the Earth is called a **cell**. * The shape of the cell depends on the **type of index**. For example, H3 uses hexagons; while Quadbin uses square. * The size of the cell depends on the **resolution**. The higher the resolution, the smaller the size of the cell. DGG systems are hierarchical, which means that every cell contains a constant number of smaller cells at a higher resolution: <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-f9850a3a8ef5e39d4f67f274582d3b42444104e5%2Fimage.png?alt=media" alt=""><figcaption>Example of how each H3 cell is sub-divided into smaller cells at higher resolutions.</figcaption></figure> ## Advantages of working with spatial indexes One of the advantages of working with spatial indexes is that operating with them in data warehouses is way more efficient and cost-effective than computing geometries. They are also smaller in size and help saving storage and reducing the volume of transferred data. When working with spatial indexes, Builder will dynamically aggregate your data into cells at a meaningful resolution depending on the current map zoom level. See the animation below for an example: <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-73857e306c2476705e2e37b8a20a5556bdf25fff%2Fh3_aggregation.gif?alt=media" alt=""><figcaption></figcaption></figure> ## Visualizing spatial index sources Your spatial index source must contain a column storing the spatial index identifier. Below is an example table containing h3 indexes, with some additional columns that contain aggregated socio-demographic data for each hexagon: | h3 | population | avg\_rent | | --------------- | ---------- | --------- | | 8a0c0036a49ffff | 103.0 | 1344.56 | | 8a0c002e4c0ffff | 1093.0 | 2087.04 | | 8a0c002e4caffff | 209.0 | 3098.39 | The `h3` column contains the indexes for H3 cells at level 10. That’s what we call the *native resolution of the data*. When you load a source in Builder, data is aggregated dynamically as you zoom in an out. This aggregation will be generated on the fly, using SQL queries that are pushed from CARTO into the data warehouse. When visualizing a spatial index source in Builder, you can control the aggregation size, to define how granular you'd like the aggregation to be when navigating through the map as part of the layer styling configuration. Learn more in this section. To understand more about performance and processing cost optimizations that should be applied to this specific source type, check [this section](/carto-user-manual/maps/performance-considerations). # Pre-generated tilesets Pre-generated tilesets are sources with tiles that have been previously generated using either the [CARTO Analytics Toolbox](/data-and-analysis/analytics-toolbox-for-bigquery/key-concepts/tilesets) or [Workflows](/carto-user-manual/workflows/components/tileset-creation). Both the creation and storage of these tilesets occur in the data warehouse. This type of data source is ideal for managing very large, static datasets. They are efficient, cost-effective, and provide high-performance visualization. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-8e3d36be4bafb6487f53d0187323ce2850c81a2c%2Fpre-generated%20tilesets.gif?alt=media" alt=""><figcaption></figcaption></figure> ## Visualizing pre-generated tilesets Builder supports the visualization of the four types of pre-generated tilesets: * **Vector Tilesets:** Pre-generated tilesets processed from point, line, or polygon tables for smooth, interactive maps. * **Point Aggregation Tilesets**: These tilesets aggregate point data with their properties into tilesets, perfect for visualizing dense point clusters. * **Quadbin Aggregation Tilesets**: Aggregated grid for scallable hierarchy management. * **H3 Aggregation Tilesets:** Aggregate quadbin indices into tilesets for scallable spatial hierarcy management. To ensure optimizal visualization and performance, you must make use of the different parameters that allow you to have full-control of the tileset specification. To learn more about this type of source in terms of performance consideration, review this [section](/carto-user-manual/maps/performance-considerations). # Rasters Raster data is composed of grids of pixels, where each pixel contains a value representing specific information, such as temperature, elevation, or vegetation indices. These datasets can represent continuous surfaces or sparse data with defined no-data regions. The CARTO platform provides seamless tools for importing, analyzing and visualizing raster sources directly in your data warehouse. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-46648dd22e1d32982606a7655ffb597b9547726c%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> ## Visualizing rasters To visualize raster sources, they must first be stored in your data warehouse using the **CARTO raster loader**. This tool ensures your raster files are properly uploaded and formatted for seamless integration with the CARTO platform. [Learn more about preparing and uploading your raster data](/carto-user-manual/data-explorer/importing-data/importing-rasters). To optimize performance, raster sources should include **overviews**—lower-resolution versions of the raster data—enabling efficient visualization at different zoom levels. Additionally, if your raster source contains a **color interpreter** (e.g., palette, grayscale, or RGB), CARTO will automatically apply default styling based on the metadata, making it easier to quickly render the raster on your map. {% hint style="warning" %} Note the current limitations and specific requirements for raster sources: * Raster sources cannot be queried directly through SQL functions, meaning they are not compatible with **SQL Editor** or **SQL Parameters**. This is similar to the behavior of pre-generated tilesets. * Raster sources are currently supported for **Google BigQuery, Snowflake and Databricks** environments. {% endhint %} --- [Next Page](https://docs.carto.com/llms-full.txt/1)

> This is part 1 of 7 of the full documentation (pages 1–100 of 693). > The content is paginated: fetch every part to see all of it. > Next part: https://docs.carto.com/llms-full.txt/1 > Page index: https://docs.carto.com/llms.txt # Welcome Welcome to the CARTO Documentation Center! All of the resources you need to unlock the power of the platform. ## Getting started with CARTO CARTO is the only cloud-first spatial platform built for accelerated, modern GIS. It runs natively on top of your cloud data warehouse platform (e.g. Google BigQuery, Snowflake, AWS Redshift, Databricks, Oracle, etc.), providing easy access to highly scalable spatial analysis and visualization capabilities in the cloud — be it for analytics, app development, data engineering, and more.


What is CARTO?	An introduction to our cloud-native platform benefits and its different components.	What is CARTO?	cartoplatform.png
Quickstart guides	Step-by-step guides to build your first maps, workflows, and applications.	Quickstart guides	First steps (1).png
CARTO Academy	Access detailed tutorials, videos and templates to learn more about geospatial analytics and to become a proficient user of the CARTO platform.	https://academy.carto.com	cartoacademy.png

## CARTO Platform CARTO unlocks the power of spatial analysis in the cloud, extending the visualization, analysis and development capabilities of the leading cloud data warehouse platforms, such as Google BigQuery, Snowflake, Oracle, and Amazon Redshift. Find out how to get the most out of our Location Intelligence platform with our product documentation:


CARTO User Manual	How to create connections to your data warehouse, build interactive maps and analytical workflows, subscribe to external data, and more.	User Manual.png	CARTO User Manual
FAQs	Frequently Asked Questions about the CARTO platform and its components.	FAQs.png	FAQs
What's New	Learn about the latest features, improvements and bug fixes in our product.	What's New.png	What's new
CARTO Self-hosted	Deploy CARTO on your own infrastructure. Learn about recommended architecture, requirements, and follow installation guides to get started.	SH (1).png	CARTO Self-Hosted

### CARTO for Agents


Connect your platform	Set CARTO up in the AI assistant you already use — Claude, ChatGPT, Gemini Enterprise, Microsoft Copilot Studio, Snowflake, Databricks, coding agents, and more.	Connect your platform.png	Connect your platform
CARTO MCP Server	Plug CARTO into your AI assistant through the Model Context Protocol: explore data, create and edit maps, and run workflows in the conversation.	CARTO MCP Server.png	CARTO MCP Server
CARTO Agent Skills	Skill playbooks that teach coding agents how to drive CARTO without re-discovering the API every session.	CARTO Agent Skills.png	CARTO Agent Skills
CARTO CLI	Script and automate CARTO from the terminal — bulk and cross-org operations, CI/CD, and deeper administration and auditing.	CARTO CLI.png	CARTO CLI

### Data and Analysis


Analytics Toolbox for BigQuery	Unlock Spatial Analytics on your BigQuery.	AT BQ.png	Analytics Toolbox for BigQuery
Analytics Toolbox for Snowflake	Unlock Spatial Analytics on your Snowflake.	AT SF.png	Analytics Toolbox for Snowflake
Analytics Toolbox for Redshift	Unlock Spatial Analytics on your Redshift.	AT RS.png	Analytics Toolbox for Redshift
Analytics Toolbox for Databricks	Unlock Spatial Analytics on your Databricks.	AT DB.png	Analytics Toolbox for Databricks
Analytics Toolbox for PostgreSQL	Unlock Spatial Analytics on your PostgreSQL.	AT PSTGRS.png	Analytics Toolbox for PostgreSQL
Data Observatory	Gain access to thousands of public and premium spatial datasets, and save time on gathering, cleaning, and analyzing data.	DO.png	Data Observatory
CARTO + Python	A set of Python packages to allow data scientists to work with CARTO from Python notebooks.	CARTO +P.png	CARTO + Python

### Development tools


CARTO + deck.gl	Build large-scale geospatial apps using deck.gl, the WebGPU-based framework for data visualization.	CARTO for deck.png	https://github.com/CartoDB/gitbook-documentation/blob/master/carto-for-developers/key-concepts/carto-for-deck.gl
CARTO for React	Build compelling spatial apps using CARTO, React and deck.gl.	CARTO for React.png	CARTO for React
CARTO + Google Maps	Integrate CARTO layers with Google Maps API and basemaps.	CARTO + Google Maps.png	Google Maps

### APIs


CARTO API	The CARTO API allows you to interact with your data in an external data warehouse to create performant cloud-native geospatial solutions.		API.png	CARTO API Reference

### Get Help


Contact Support	Get in touch with our team of first-class geospatial specialists.	Support.png	Support Packages
Join our community of users in Slack	Our community of users is a great place to ask questions and get help from CARTO experts.	Frame 1 (11).png	https://join.slack.com/t/cartousercommunity/shared_invite/zt-t7t7k5s4-3c4pZJLrLlkVow3AEDt~ZQ
All previous libraries and components	Including API v2, CARTO.js, CartoCSS, Torque.js, CARTOframes and others.	Legacy.png	Previous libraries and components

# What's new Learn about the latest features, improvements and fixes in our product. {% hint style="success" %} This page will always reflect the latest changes in the CARTO platform. Older release notes will be archived and are available in the left menu and the search bar. {% endhint %} {% updates %} {% update date="2026-10-07" tags="new,ai-agents" %} ## AI Agents can refresh the data on your map Ask an AI Agent to run an [MCP Tool](/carto-user-manual/workflows/workflows-as-mcp-tools) that changes your data and the map now updates by itself. The layers, the widgets and the tables all show the new numbers, nobody has to reload the page, and your conversation with the Agent carries on. For example, ask an Agent to rebuild the drive-time areas around your stores for a longer drive, or to score your candidate sites again after you change what matters most. The new result lands on the map you are already looking at. Learn more in the [AI Tools Reference](/carto-user-manual/ai-agents/ai-tools-reference) documentation.

{% endupdate %} {% update date="2026-10-06" tags="new,workflows" %} ## Five new components to analyze embeddings in Workflows The Analytics on Embeddings extension package for BigQuery grows from four to nine components, covering the whole path from raw embeddings to an answer. [Embedding Profile](/carto-user-manual/workflows/components/embedding-analytics#embedding-profile) summarizes many locations into one vector, such as a brand from its branches or a store from the areas its visitors come from. [Mean Deviation](/carto-user-manual/workflows/components/embedding-analytics#mean-deviation) flags the places that break from their baseline, and [Neighborhood Deviation](/carto-user-manual/workflows/components/embedding-analytics#neighborhood-deviation) finds where the embedding field changes across space. [Spatial Aggregation](/carto-user-manual/workflows/components/embedding-analytics#spatial-aggregation) moves embeddings to your own polygons, and [Vector Normalization](/carto-user-manual/workflows/components/embedding-analytics#vector-normalization) makes the new Dot product metric safe to use. The existing components get updates too. Similarity Search and Change Detection now offer a faster Dot product metric alongside Cosine, and Visualization can render a bivariate map. If the package is already installed in a connection, select **Update extension package** in the Installed tab of the extensions gallery, then check the documentation for the settings that changed in existing workflows. Learn more in our [Analytics on Embeddings documentation](/carto-user-manual/workflows/components/embedding-analytics). {% endupdate %} {% update date="2026-10-01" tags="new,builder" %} ## A new layout for Builder maps Builder maps have a new layout that gives your widgets and parameters more room, on any screen. It's built for dashboard-style maps, where your audience needs the key numbers and filters at a glance. * **Flexible widgets panel.** Show widgets in one or two columns, dock the panel next to the map or float it on top, and give key widgets the full width. * **Parameters bar.** SQL parameters sit above the map with their current values always visible, in the order you choose. * **Any screen.** Maps adapt to tablets, phones and narrow embeds, keeping the map front and center. Viewers can also chat with your AI Agent on mobile. Learn more in our [Map layout documentation](/carto-user-manual/maps/map-layout).

A tour of the new Builder layout: widgets panel, parameters bar and maps on tablets and phones

{% endupdate %} {% update date="2026-09-23" tags="new,platform" %} ## Claude 5, Gemini 3.8 and GPT-6 Astra are now in CARTO CARTO AI now offers the newest generation of models, including Claude Opus 5.5 within a day of its launch. The CARTO-managed set adds `claude-sonnet-5`, our new default for geospatial use cases, `claude-opus-5.5`, our most capable model for the hardest geospatial reasoning, and `gemini-3.8-flash` for fast, high-volume interactions. If you bring your own provider, the newest models are available too. `claude-fable-5.1`, `claude-opus-5` and `claude-sonnet-5` run on Anthropic, Bedrock and Vertex AI, with `claude-opus-5.5` also on Vertex AI. Claude 5 models are available on Databricks as well. `gemini-3.8-flash` runs on Vertex AI, Google AI Studio and Databricks, and `gpt-6-astra` on OpenAI. Learn more in the [CARTO AI settings](/carto-user-manual/settings/carto-ai) documentation.

{% endupdate %} {% update date="2026-09-21" tags="new,workspace" %} ## Share connections with specific users and groups You can now share any connection with specific users or groups, not just with your entire organization, using the same sharing model as maps and workflows. The dialog also makes clear what sharing means for each connection: recipients either access the data through the identity configured in the connection, or authenticate with their own warehouse credentials. Learn more in our [Sharing connections documentation](/carto-user-manual/connections/sharing-a-connection).

{% endupdate %} {% update date="2026-09-10" tags="improvement,workflows" %} ## Choose the file format when exporting from Workflows Exporting a node result is no longer limited to CSV. Pick **CSV**, **GeoJSON**, **Shapefile**, **GeoParquet**, **GeoPackage** or **KML** and get a file you can open straight away in desktop GIS, Google Earth or your data pipeline, with no conversion step. These are the same formats available in Builder. CSV stays selected by default, and Viewers of a shared workflow get the same choice when the Editor allows them to export. Learn more in our [Exporting data documentation](/carto-user-manual/workflows/exporting-data).

{% endupdate %} {% update date="2026-09-07" tags="new,platform" %} ## Deploy CARTO Self-Hosted on any cloud CARTO Self-Hosted is now provider agnostic. Alongside AWS, Google Cloud, Azure, and Oracle Cloud, any infrastructure that provides **standard Kubernetes**, a **PostgreSQL** database, and **S3-compatible object storage** can run a complete CARTO deployment: regional providers such as OVHcloud or Scaleway, **sovereign clouds** operated within national borders, and **private clouds** or on-premises platforms with S3-compatible storage such as Ceph. This is possible because CARTO Self-Hosted now works with any S3-compatible object storage, so it adapts to the infrastructure you already run. Configuration follows the same steps as before, with a couple of extra fields for your storage endpoint. This opens CARTO to organizations whose data residency or sovereignty requirements call for infrastructure in a specific jurisdiction or in their own data center. Available since CARTO Self-Hosted [2026.8.11](https://docs.carto.com/pages/bDddXkUezz5UkejnQDMd#2026.8.11). Learn more in our [Object Storage prerequisites](/carto-self-hosted/planning/prerequisites/object-storage) and [Configure your own buckets](/carto-self-hosted/configuration/data-and-storage/configure-your-own-buckets) documentation.

{% endupdate %} {% update date="2026-09-03" tags="new,builder" %} ## Dashed strokes and fill patterns in Builder Your maps are no longer limited to solid lines and flat fills. Line layers and polygon borders can now be drawn as **Solid**, **Dashed** or **Dotted**, with control over the dash and gap lengths, and polygons can be filled with a **pattern** (horizontal or vertical lines, forward or backward diagonals, cross-hatch, dots or checkerboard) at the density and scale you choose. This unlocks the cartographic conventions your audience already reads: a dashed border for a proposed route or a boundary that is not yet final, hatching for a restricted or protected zone, a pattern for areas where data is missing or uncertain. Stroke styles and fill patterns are reflected in the legend of your published maps, so the people you share with get the same reading. Learn more in our [Layer styling documentation](/carto-user-manual/maps/layers#stroke-styles).

{% endupdate %} {% update date="2026-08-26" tags="improvement,carto-for-agents" %} ## All of CARTO, in every agentic platform - via our MCP Server The CARTO MCP Server now exposes **every CARTO capability as an MCP tool**, so your agents can explore, create, edit and manage all of your CARTO content from the agentic platform your team already uses — no terminal and no coding required. The tools are organized in four categories: * **Maps**: create, update, validate, read and render Builder maps. * **Workflows**: create, run, schedule and inspect Workflows, including Workflows published as MCP tools. * **Data**: explore connections and tables, run SQL, geocode, create routes and isochrones, and import or export data. * **Workspace**: manage users, credentials, projects and activity data. Because MCP is an open standard, the same experience is available across **Claude, ChatGPT, Microsoft Copilot Studio, Gemini Enterprise, Snowflake Cowork, Databricks Agents, Oracle**, and any other MCP-compatible host. Governance is unchanged: every tool call goes through the same platform APIs, with the user's own credentials, so existing roles, permissions and row-level security in your data warehouse still apply — if a user can't edit a map, neither can their agent. Your data never leaves the warehouse, and every action is logged and attributable in your Activity Data. To get started, connect the [CARTO MCP Server](/carto-for-agents/mcp-server) to your platform following our connection guides, and pair it with our [CARTO Agent Skills](/carto-for-agents/agent-skills) to bring geospatial expertise along with the capabilities.

{% endupdate %} {% update date="2026-08-21" tags="new,workspace" %} ## Analyze your Usage quota consumption without exporting data The new **Analytics** tab in **Settings > Quotas & Activity** gives Admins a visual breakdown of how the organization is consuming its Usage quota, right in the Workspace. See consumption over time, per period or cumulative, stacked by CARTO API/service, for the time frame you choose. Ranked tables surface your top consumers by user, client, map, and workflow, each searchable by name, and clicking a period in the chart scopes those tables to that window. Learn more in our [Usage analytics documentation](/carto-user-manual/settings/quotas-and-rate-limits/usage-analytics).

{% endupdate %} {% update date="2026-08-06" tags="new,workspace" %} ## See which API Access Token is consuming your quota Usage from [API Access Tokens](/carto-user-manual/developers/managing-credentials/api-access-tokens) is now attributed to the token that produced it, instead of being lumped together as `public` traffic. In the [API Usage](/carto-user-manual/settings/activity-data/activity-data-reference#api-usage) table of your Activity Data, requests made with a token now report a `user_id` like `token:_`, so you can **tell at a glance which integration, script, or application is driving your Usage Quota** — and tie consumption back to a specific team or project. As with the rest of your Activity Data, you can explore it in the Workspace, through the CARTO CLI, or with CARTO for Agents. Learn more in the [API Usage reference](/carto-user-manual/settings/activity-data/activity-data-reference#api-usage).

{% endupdate %} {% update date="2026-08-05" tags="new,workspace" %} ## Personal settings for all users You can now manage your CARTO account and track your own consumption from the new **Personal** section of the Settings. In **Profile** you'll find your account details, and you can change your password or delete your user. In **Usage** you can track your individual consumption of the Usage, LDS, and AI quotas, along with any limit your Admin has set for you. Learn more in our [Personal settings documentation](/carto-user-manual/settings/personal-settings).

{% endupdate %} {% update date="2026-08-05" tags="new,workspace" %} ## Automatic user and group provisioning with SCIM Organizations using Single Sign-On can now provision users and groups automatically with **SCIM**. Your Identity Provider pushes changes to CARTO as they happen, so users exist before their first login, group changes apply right away, and users unassigned in your IdP lose access immediately instead of at their next login attempt. This also applies to [group role mapping](/carto-user-manual/settings/users-and-groups/mapping-groups-to-user-roles), so a move between groups grants the new role without waiting for a login. SCIM is set up by our Support Team on top of an existing SSO integration, and is available for **Enterprise Large** plans and above. Learn more in our [SCIM provisioning documentation](/carto-user-manual/settings/users-and-groups/scim-provisioning). {% endupdate %} {% update date="2026-07-29" tags="private-beta,data-observatory" %} ## PlacePulse Embeddings: a fingerprint for every place in the US PlacePulse Embeddings, a Geospatial Foundation Model built by CARTO with [Applied Geographic Solutions (AGS)](https://appliedgeographic.com/), encodes the characteristics of a place into a single 256-dimensional vector, one for every **H3 Resolution 7** cell across the entire US. Demographics, local economy, business mix, built environment and climate risk, all compressed into one fingerprint per place. Distributed through the Data Observatory and ready to use with the Analytics on Embeddings components in Workflows: twin areas, white space, segmentation, or ready-made features for a predictive model. Currently in **private preview** for a selected group of customers. Read the [blog post](https://carto.com/blog/placepulse-embeddings-fingerprint-every-place-us/) or [request early access](https://docs.google.com/forms/d/e/1FAIpQLSehAncVLjxLLcgyK8Ha5__l803lbtWMxKgH15LCfUhIHFS0ww/viewform?usp=dialog).

{% endupdate %} {% update date="2026-07-28" tags="new,builder" %} ## Export your Builder maps as high-resolution images You can now export your Builder map as a high-resolution PNG, ready to use in reports, slide decks, brochures, and print publications. Choose the exact image dimensions you need, and Builder will generate the export at that size, keeping labels, lines, and symbols sharp. The exported image captures your current map view, including the visible layers and basemap. You can also allow end users of shared and public maps to export images themselves. Learn more in our [Exporting map images documentation](/carto-user-manual/maps/exporting-map-images).

{% endupdate %} {% update date="2026-07-24" tags="new,workflows" %} ## Test your MCP Tools before agents call them You can now test a Workflow-backed **MCP Tool** directly from the canvas, running it exactly as an AI Agent would — before you enable it or wire it into an agent. Open the **Run** dropdown and choose **Run MCP Tool test** to execute the tool through the same CARTO MCP Server path a real agent uses. Enter test values in the input parameters popover (pre-filled from your workflow variables), then watch the run stream step by step in the Messages tab. For **Sync** tools you get the response immediately; for **Async** tools you see the full job submission, status polling, and result retrieval an agent goes through. The response is rendered as expandable JSON with row count and execution time, so you can preview the exact output, understand timing, and copy it to write better tool descriptions and agent instructions. A session-scoped Run history keeps every test run, including failures, so debugging no longer means guessing from a live agent. Learn more in the [Workflows as MCP Tools](/carto-user-manual/workflows/workflows-as-mcp-tools#test-your-mcp-tool) documentation. {% embed url="" %} {% endupdate %} {% update date="2026-07-21" tags="new,builder" %} ## Give your AI Agents spatial and business context with semantic models You can now add a **semantic model** to an AI Agent, a structured layer of business meaning over your data. It tells the Agent what your tables and columns mean, how your datasets relate, how your metrics are calculated, and how your spatial data is structured, so the Agent writes correct SQL and applies your definitions consistently. It builds on the open [Apache Ossie](https://ossie.apache.org/) standard with a CARTO extension for geospatial fields. You can write it in Builder, import an existing YAML, or let the Agent Config Assistant generate it from your data. Learn more in our [Semantic model documentation](/carto-user-manual/ai-agents/semantic-model).

{% endupdate %} {% update date="2026-07-20" tags="new,workflows" %} ## Revamped Import/Export components in Workflows Moving data in and out of Workflows now works across **BigQuery, Snowflake, Redshift, Databricks and Oracle** from the same canvas: * **Import from URL** and **Import from URL using table** now run on Databricks and Oracle, in addition to BigQuery, Snowflake and Redshift. * **Export as File** is a new component that exports your table to a presigned download link, with no bucket configuration required, on all of these providers. * **Export Tables as PDF** turns your workflow results into a shareable PDF report — with a custom title, descriptions and page orientation — on all of these providers. * **Send by Email** now works across all of these providers too, and can attach a download link to the message. The previous BigQuery-only export components remain available as **Export to Bucket (Legacy)** and **Send by Email (Legacy)** for your existing workflows. Under the hood, this adds new **import** and **export** modules to the CARTO Analytics Toolbox for [Databricks](/data-and-analysis/analytics-toolbox-for-databricks/reference/import) and [Oracle](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/import). Learn more in the [Input / Output components](/carto-user-manual/workflows/components/input-output) documentation. {% embed url="" %} {% endupdate %} {% update date="2026-07-20" tags="new,platform" %} ## Import and export geospatial data on Databricks and Oracle You can now import files into your warehouse and export data back out on **Databricks** and **Oracle** connections, just like you already do on BigQuery, Snowflake, Redshift and PostgreSQL. Bring data in from a local file or a URL in Data Explorer, and export your results from Builder and Workflows in the geospatial formats you work with, including CSV, GeoJSON, Shapefile, GeoPackage, KML, GeoParquet and more. This is powered by our new Import/Export engine, which brings consistent format support across providers with no manual conversion required. Learn more in the [Importing data](/carto-user-manual/data-explorer/importing-data) and [Exporting data](/carto-user-manual/maps/exporting-data) documentation.

{% endupdate %} {% update date="2026-07-16" tags="new,builder" %} ## Filter your data by clicking directly on the map You can now filter your Builder map by clicking directly on a feature, alongside widgets, parameters, and the selection tool. Filter just the selected feature or, for polygons, H3, and Quadbin cells, use the clicked feature as a spatial mask to filter all intersecting layers at once. Click-based filters automatically propagate to widgets, PDF exports, and viewport data exports, just like any other filter. Click a postcode or region to instantly update population and other metrics in your widgets, or click individual stores, assets, or sensors to isolate and export only those features. Learn more in our [Interactions documentation](/carto-user-manual/maps/interactions#filter-by-feature).

{% endupdate %} {% update date="2026-07-14" tags="new,builder" %} ## Manage your organization's custom markers in one place Custom markers have always been available in Builder, but Editors had to upload and manage them map by map. Now Admins can manage a shared set of custom point markers for the whole organization from **Settings > Customizations > Markers**, and Editors pick from them in Builder without re-uploading the same icons into every map. Replace or rename a marker once and the change flows to every map that uses it, so branding stays consistent as your icons evolve. Learn more in the [Configuring custom markers](/carto-user-manual/settings/customizations/configuring-custom-markers) documentation.

{% endupdate %} {% update date="2026-07-06" tags="new,builder" %} ## More export formats and controls in Builder Data exports in Builder are now more flexible and more governed. Beyond CSV, you can export to **GeoJSON**, **Shapefile**, **GeoParquet** and **KML**, so you can take a filtered dataset straight into the tools you already use without any manual conversion. As an Editor, you stay in control of what leaves your map: choose which sources are exportable, whitelist the columns that can be exported so sensitive attributes stay in your warehouse, and set the formats available per source. Every export honors the current map state, so filters, SQL parameters and the viewport are all respected. Learn more in our [Exporting data documentation](/carto-user-manual/maps/exporting-data).

{% endupdate %} {% update date="2026-07-03" tags="new,workspace" %} ## Organize your maps and workflows with projects and folders You can now organize your maps and workflows into **projects and folders** instead of one flat list. Group related work together, nest folders as deep as you need, and move or create maps and workflows right where they belong. Projects keep your Workspace tidy and make collaboration easier: share a project or folder once and everything inside inherits those access permissions. You set permissions in one place instead of doing it asset by asset. When an asset belongs in more than one project, add a shortcut instead of moving it. Learn more in the [Projects](/carto-user-manual/projects) documentation.

{% endupdate %} {% update date="2026-07-03" tags="new,platform" %} ## More flexible sharing for maps and workflows Sharing maps and workflows is now more flexible. Share assets with specific people or groups, with your whole organization, or publicly, and switch between those modes in a single click. Switching keeps the people and groups you already added with the same access permissions, so you never set anything up twice. Projects and folders share the same flexiblity: share once, and every asset inside a project or folder inherits that access. Learn more in the [map sharing](/carto-user-manual/maps/sharing-and-collaboration) and [workflow sharing](/carto-user-manual/workflows/sharing-workflows) documentation.

{% endupdate %} {% update date="2026-07-02" tags="builder,improvement" %} ## Single-select mode for text parameters Text parameters in Builder can now be set to single value instead of always allowing multiple selections. Viewers pick exactly one option from a radio list, and you decide which value is selected by default. Single-select fits any map that should answer for one thing at a time: a single product line, region, store, audience segment, or scenario in a what-if comparison. The viewer picks one option and the map returns one clear, correct result. Learn more in the [Text parameter](/carto-user-manual/maps/sql-parameters/text-parameter) documentation.

{% endupdate %} {% update date="2026-07-01" tags="builder,improvement" %} ## Pie and Time Series widgets now sync with your layer colors Pie and Time Series widgets in Builder can now inherit the colors of the layer they visualize. When a widget uses the same column your layer is styled by, it automatically picks up the layer's category colors, so the widget, the map, and the legend all match, with no extra setup. A category shown in purple on the map is purple in the widget too. Colors are now stable within a session as well: even without a layer match, each category keeps its color as you zoom, pan, and filter, instead of shifting with the data order. This applies to the Pie widget and to the Time Series widget with Split by. Learn more in the [Pie widget](/carto-user-manual/maps/widgets/pie-widget) and [Time Series widget](/carto-user-manual/maps/widgets/time-series-widget) documentation.

{% endupdate %} {% update date="2026-06-29" tags="new,builder" %} ## Labels for polygons and lines in Builder You can now add text labels directly to polygon and line layers, not just points. Turn labels on from the **Labels** section of the layer panel and choose the column to display. CARTO places each label automatically, at the center of every polygon and along the middle of every line. For lines, you can also pick a unique ID column so a feature that crosses several tiles, like a long road, shows a single label instead of one per tile. Learn more in our [Layers documentation](/carto-user-manual/maps/layers#labels).

{% endupdate %} {% update date="2026-06-29" tags="new,platform" %} ## The latest AI models are now in CARTO CARTO AI now offers the latest generation of models across every supported provider. The CARTO-managed set adds `claude-opus-4.8`, our most capable model for the hardest geospatial reasoning, and `gemini-3.5-flash` for fast, high-volume interactions. If you bring your own provider, the newest models are available too: the GPT-5.5 and GPT-5.4 families on OpenAI, Azure, Snowflake and Databricks, `claude-opus-4.8` on Anthropic, Bedrock, Vertex AI, Snowflake and Databricks, `gemini-3.5-flash` on Vertex AI, Google AI Studio and Databricks, and xAI Grok 4.3 and 4.20 on Oracle. Learn more in the [CARTO AI settings](/carto-user-manual/settings/carto-ai) documentation.

{% endupdate %} {% update date="2026-06-25" tags="new,builder" %} ## Organize your layers into groups in Builder You can now organize the layers in your map into named, collapsible **groups**. Related layers fold into tidy sections in the layer panel, so a map with a long list of layers stays easy to read and work with. Group layers however makes sense for your map, collapse the ones you're not using, and turn a whole group's visibility on or off in one click. Learn more in our [Layers documentation](/carto-user-manual/maps/layers#layer-groups).

{% endupdate %} {% update date="2026-06-12" tags="improvement,ai-agents" %} ## AI Agents are more visible and accessible in your maps The AI Agent in your published maps now has a more prominent place in the interface. Instead of a button users had to find and click, the Agent is immediately visible alongside the map when it loads — making it easier for your users to start a conversation and get answers right away. Users can also expand the Agent for a more focused conversation when they need it. Learn more about [sharing your AI Agent](/carto-user-manual/ai-agents/sharing-your-agent) and [creating AI Agents](/carto-user-manual/ai-agents) in our documentation.

{% endupdate %} {% update date="2026-06-05" tags="new,platform" %} ## Bring any custom AI provider, proxy or gateway to CARTO CARTO already supports nine AI providers out of the box — including Google Vertex AI, OpenAI, Anthropic, AWS Bedrock, Azure OpenAI, Snowflake, Databricks, and Oracle. Now you can connect any OpenAI-compatible endpoint as well, whether that's an LLM gateway or your own self-hosted models. Connect one or more providers, and their models become available across CARTO's AI features — [AI Agents](/carto-user-manual/ai-agents), the [Agent Config Assistant](/carto-user-manual/ai-agents/agent-config-assistant), and the [AI Assistant in Data Observatory](/carto-user-manual/data-observatory/accessing-and-browsing-the-spatial-data-catalog). Learn more in the [CARTO AI settings](/carto-user-manual/settings/carto-ai) documentation.

{% endupdate %} {% update date="2026-06-03" tags="new,ai-agents" %} ## Full visibility into your AI Agent's behavior Get full visibility into your AI Agent's actions with new **tool traceability**. You can now see which tools were executed, the parameters used, and their outputs, all directly in the conversation. Inspect the SQL generated by `execute_query`, the arguments passed to a [Workflows MCP Tool](/carto-user-manual/workflows/workflows-as-mcp-tools), or the inputs of any other tool the Agent ran, so you know exactly how the Agent reached its answer. Learn more about the [tools available for AI Agents](/carto-user-manual/ai-agents/working-with-tools) in our documentation.

{% endupdate %} {% update date="2026-05-27" tags="new,analytics-toolbox" %} ## New modules in the Analytics Toolbox for Oracle The [Analytics Toolbox for Oracle](/data-and-analysis/analytics-toolbox-for-oracle) (v1.1.0) expands its capabilities on Oracle Autonomous Database with three new modules. The new [`data`](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/data) module brings **data enrichment** to Oracle, with the [ENRICH\_POINTS](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/data#enrich_points), [ENRICH\_POLYGONS](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/data#enrich_polygons), [ENRICH\_POLYGONS\_WEIGHTED](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/data#enrich_polygons_weighted) and [ENRICH\_GRID](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/data#enrich_grid) procedures (plus their `_RAW` variants), so you can augment your spatial data with variables from other datasets directly in SQL. This release also adds the [`h3`](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/h3) and [`quadbin`](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/quadbin) **spatial indexing** modules. The `h3` module brings the full set of H3 functions to Oracle, covering index conversion ([H3\_FROMGEOGPOINT](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/h3#h3_fromgeogpoint), [H3\_BOUNDARY](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/h3#h3_boundary), [H3\_CENTER](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/h3#h3_center)), hierarchy traversal ([H3\_TOPARENT](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/h3#h3_toparent) / [H3\_TOCHILDREN](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/h3#h3_tochildren)), neighborhood traversal ([H3\_KRING](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/h3#h3_kring)) and polygon-to-grid conversion ([H3\_POLYFILL](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference/h3#h3_polyfill)), so you can index, aggregate and analyze your data on hexagonal grids natively in Oracle. The `quadbin` module provides the equivalent set of functions for the Quadbin grid. Learn more in the [Analytics Toolbox for Oracle release notes](/data-and-analysis/analytics-toolbox-for-oracle/release-notes) and the [SQL reference](/data-and-analysis/analytics-toolbox-for-oracle/sql-reference). {% endupdate %} {% update date="2026-05-27" tags="new,analytics-toolbox" %} ## New capabilities in the Analytics Toolbox for Databricks The [Analytics Toolbox for Databricks](/data-and-analysis/analytics-toolbox-for-databricks) (v2.4.0) extends its [`statistics`](/data-and-analysis/analytics-toolbox-for-databricks/reference/statistics) module with a new [HOTSPOT\_ANALYSIS](/data-and-analysis/analytics-toolbox-for-databricks/reference/statistics#hotspot_analysis) procedure. It locates hotspot areas by combining several variables' [Getis-Ord Gi\*](/data-and-analysis/analytics-toolbox-for-databricks/reference/statistics#getis_ord_h3) statistics using Stouffer's method, and works on either H3 or Quadbin grids. The Analytics Toolbox for Databricks also includes a [`data`](/data-and-analysis/analytics-toolbox-for-databricks/reference/data) module for **data enrichment**, with the [ENRICH\_POINTS](/data-and-analysis/analytics-toolbox-for-databricks/reference/data#enrich_points), [ENRICH\_POLYGONS](/data-and-analysis/analytics-toolbox-for-databricks/reference/data#enrich_polygons), [ENRICH\_POLYGONS\_WEIGHTED](/data-and-analysis/analytics-toolbox-for-databricks/reference/data#enrich_polygons_weighted) and [ENRICH\_GRID](/data-and-analysis/analytics-toolbox-for-databricks/reference/data#enrich_grid) procedures (plus their `_RAW` variants), so you can augment your spatial data with variables from other datasets directly in SQL. Learn more in the [Analytics Toolbox for Databricks release notes](/data-and-analysis/analytics-toolbox-for-databricks/release-notes) and the [SQL reference](/data-and-analysis/analytics-toolbox-for-databricks/reference). {% endupdate %} {% update date="2026-05-26" tags="new,workflows" %} ## Version history in Workflows Workflows now keep a complete **version history**. CARTO automatically captures versions as you work, and you can also save named versions to mark important milestones. Each time you enable or update an execution method — a schedule, an API endpoint, an MCP Tool, or Viewer mode — that snapshot is recorded and marked as the **published version** for that method, so consumers keep running against a stable state while you keep editing. From the Version History dialog you can browse, search, and filter past versions, preview each one on the canvas, restore the workflow to an earlier state, or duplicate a new workflow from any historical version. Learn more in our [Version history documentation](/carto-user-manual/workflows/version-history). {% embed url="" %} {% endupdate %} {% update date="2026-05-26" tags="new,workspace" %} ## Usage attribution by map and workflow Admins can now see which specific **maps and workflows** are consuming their [Usage Quota](/carto-user-manual/settings/quotas-and-rate-limits/understanding-your-organization-quotas). The [Activity Data](/carto-user-manual/settings/activity-data) export now includes `map_id` and `workflow_id` columns in the API Usage table, making it easy to understand where your Usage Quota is going, identify high-cost maps and workflows, and tie consumption back to specific teams or projects. Learn more in our [Activity Data reference](/carto-user-manual/settings/activity-data/activity-data-reference#api-usage).

{% endupdate %} {% update date="2026-05-20" tags="new,workspace" %} ## Wildcard patterns in API Access Token grants API Access Tokens now accept **wildcard patterns** in the **Table, Tileset, Raster source or Pattern** grant. Instead of listing resources one by one, you can use `*` to match multiple resources at once, for example `carto.shared.*` to cover everything under `carto.shared` or `carto.shared.CARTO_*` to cover only resources that share a naming convention. Patterns also match resources created after the token was issued, so you no longer need to re-issue tokens when new tables land. Learn more in our [API Access Tokens documentation](/carto-user-manual/developers/managing-credentials/api-access-tokens#wildcard-patterns).

{% endupdate %} {% update date="2026-05-21" tags="new,workspace" %} ## Granular controls for CARTO AI features Organization Admins can now control CARTO AI at the feature level from **Settings > CARTO AI**. In addition to the organization-wide **Enable CARTO AI** toggle, each individual AI feature has its own switch and its own default model selector. The granular controls currently cover **AI Agents in Builder maps** and the new **AI Assistant in Data Observatory**, with more features to follow. The per-feature default model overrides the organization-wide default for that specific feature, so different capabilities can run on different models. Newly introduced features are disabled by default, so Admins need to enable them explicitly before they become available to users. Learn more in our [CARTO AI settings documentation](/carto-user-manual/settings/carto-ai#ai-features).

{% endupdate %} {% update date="2026-05-21" tags="new,data-observatory" %} ## AI Assistant in Data Observatory Finding the right dataset in the Spatial Data Catalog now takes a sentence instead of a series of filter clicks. The new **AI Assistant in Data Observatory** lets you describe what you need in natural language and applies the matching filters to the catalog for you. Open the assistant with the **Ask AI** button at the top of the Data Observatory catalog, ask something like *"What datasets would help analyze consumer purchasing patterns in the UK?"*, and the sidebar will filter the catalog down to the datasets that fit. You can keep iterating in the same conversation to refine the results or change direction, and manual filters remain available at any time. Learn more in our [Browsing the Spatial Data Catalog documentation](/carto-user-manual/data-observatory/accessing-and-browsing-the-spatial-data-catalog#ai-assistant-in-data-observatory).

{% endupdate %} {% update date="2026-05-19" tags="new,builder" %} ## Custom SQL aggregation expressions in Builder Spatial index layers (H3, Quadbin) and aggregated-by-geometry layers in Builder now support **custom SQL aggregation expressions** for styling and interactions. Apart from the predefined `avg`, `sum`, `min`, `max` set, you can write any aggregation expression that runs on your data warehouse. This is useful for derived metrics like rates, ratios and weighted averages. ```sql SUM(female) / NULLIF(SUM(population), 0) ``` Learn more in our [H3 layer documentation](/carto-user-manual/maps/layers/h3#custom-aggregation-expressions).

{% endupdate %} {% update date="2026-05-18" tags="improvement,builder" %} ## Scale point radius with zoom in Builder Point layers in Builder now support a new **Scale with zoom level** option for radius. Instead of a fixed pixel size, points grow and shrink with the map zoom, staying visually proportional to context. A **Min / Max bounds** clamp keeps points readable at extreme zooms, and the option applies to both simple points and custom markers. Learn more in our [Point layer documentation](/carto-user-manual/maps/layers/point#scale-with-zoom-level).

{% endupdate %} {% update date="2026-05-14" tags="new,carto-for-agents" %} ## CARTO for Agents: bring the platform into your AI workflows AI agents are quickly becoming part of how teams build with spatial data. We're launching **CARTO for Agents**, three new capabilities that put the entire CARTO platform within reach of the AI agents you already use: authoring Builder maps and Workflows, managing connections, browsing the Data Observatory, running imports and exports, and anything else you do day to day. * [**CARTO CLI**](/carto-for-agents/cli). A script-friendly command-line for the platform that humans run in a terminal and agents call as a tool. The latest release adds first-class Builder map and Workflow authoring from JSON bundles. * [**CARTO MCP Server**](/carto-for-agents/mcp-server). A hosted [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes built-in CARTO tools, plus any workflow you publish, to web and desktop AI clients like Claude.ai, ChatGPT, and Gemini. * [**CARTO Agent Skills**](/carto-for-agents/agent-skills). A public catalog of skill playbooks at [`CartoDB/agent-skills`](https://github.com/CartoDB/agent-skills) that teaches coding agents (Claude Code, Codex, Cursor, Gemini CLI) how to drive CARTO without re-discovering the API every session. The three pieces work together depending on the scenario. A chat agent in Claude.ai, ChatGPT, or Gemini connects through the MCP Server. A coding agent in Claude Code, Cursor, or Codex combines the CLI with the Agent Skills, which teach it the right flags and patterns for each task. Learn more in our [CARTO for Agents documentation](/carto-for-agents/carto-for-agents).

{% endupdate %} {% update date="2026-05-14" tags="new,workspace" %} ## CARTO AI Analytics for organization Admins Organization Admins now have a dedicated **Analytics** tab in Settings > CARTO AI to see how CARTO AI is being used across the organization. The tab is split into three views: **All activity** with active users and consumption of your AI and agentic usage quotas, **CARTO Agents** with activity from AI Agents created in Builder, and **External Agents** with activity driven from external clients consuming CARTO through the MCP Server and the CARTO CLI. Learn more in our [CARTO AI Analytics documentation](/carto-user-manual/settings/carto-ai/carto-ai-analytics).

{% endupdate %} {% update date="2026-05-14" tags="new,workspace" %} ## Quota controls for organization Admins Organization Admins can now cap how much of each quota a specific user or group is allowed to consume, directly from **Settings > Quotas & Activity > Quota Limits**. Limits can be set for the Usage quota, the Location Data Services quota, and the AI quota, and they are hard limits: once a user or group reaches the limit, they are blocked from consuming more of that quota until an Admin raises or removes the limit. Learn more in our [Managing quotas documentation](/carto-user-manual/settings/quotas-and-rate-limits/managing-quotas).

{% endupdate %} {% update date="2026-05-08" tags="new,builder" %} ## Google Photorealistic 3D Tiles in Builder Bring your maps to life with our new CARTO Builder basemap option: **Google Photorealistic 3D Tiles**. This high-fidelity representation of the world built from aerial and satellite imagery lets you explore your data on top of detailed 3D buildings and terrain. Your data will automatically cover the surface of buildings and other 3D terrain features, allowing you to understand the data in real-world context. This can be incredibly useful for urban planning, real estate or insurance use cases. Google Photorealistic 3D Tiles span over **2,500 cities across 49 countries.** See Google's [Photorealistic 3D Tiles coverage](https://developers.google.com/maps/documentation/tile/3d-tiles-overview) for the latest list of supported areas. Ready to try it? Learn more in our [Basemaps documentation](/carto-user-manual/maps/basemaps).

{% endupdate %} {% update date="2026-04-20" tags="improvement,builder" %} ## Reorder categorical legend entries in Builder Categorical and ordinal legend entries can now be reordered in Builder to improve map readability. Categories can be sorted by frequency or alphabetically, in ascending or descending order.\ \ Reordering only affects the legend’s reading order, colors remain fixed to each category, so the map visualization does not change. Learn more in our [Legend documentation](/carto-user-manual/maps/legend).

{% endupdate %} {% update date="2026-04-15" tags="improvement,builder" %} ## Click interactions now show every overlapping feature Click interactions in Builder now paginate across every feature at clicked location, in both pop-up and info panel modes. When overlapping polygons, overlapping lines, or multiple records sharing the same geometry sit at the same spot, you can step through all of them within a layer instead of only seeing the top one.\ \ Previously, clicking a stacked location surfaced only a single feature and the rest were unreachable without zooming in or filtering the data. The new prev/next controls let you browse all of them, with the map highlighting updating as you paginate. Learn more in our [Click interactions documentation](/carto-user-manual/maps/interactions#click-type-interactions).

{% endupdate %} {% update date="2026-03-30" tags="new,carto-for-developers" %} ## Build AI-first spatial apps with CARTO Agentic Tools for developers Building AI-powered apps with geospatial capabilities just got a lot easier. We're releasing `@carto/agentic-deckgl`, an open-source TypeScript library built on [CARTO + deck.gl](https://carto.com/blog/modern-spatial-app-development-carto/) that lets any AI Agent create and style map layers, run spatial analytics, and interact with the map through natural language — with one npm install. It's framework-agnostic, includes Zod-validated tool definitions, a geospatial system prompt builder, and SDK converters for major AI frameworks. The library gives AI Agents full control over the map experience: creating and styling vector tile, H3, GeoJSON, and raster layers from any CARTO data source; navigating the globe with smooth transitions; switching basemaps; placing and managing markers; applying spatial filters from user-drawn areas or analytical workflows; and managing widgets, visual effects, and layer ordering. Learn more about this new library in our [product announcement](https://carto.com/blog/carto-agentic-tools-for-developers/).

{% endupdate %} {% update date="2026-03-30" tags="new,builder" %} ## Create AI Agents through conversation with the new Configuration Assistant Creating [AI Agents](/carto-user-manual/ai-agents) just got significantly easier. The new **Agent Configuration Assistant** lets you design, set up, and iterate on your agents using natural language. Instead of manually defining instructions, selecting tools, and configuring capabilities step by step, you can now **simply describe what your agent should do**. The Assistant generates a complete configuration for you — including the use case, structured instructions, model selection, tool setup, capabilities, and a tailored introduction message. The Assistant is context-aware, meaning its recommendations are grounded in your actual map. It understands your datasets, layers, widgets, and available tools, helping you create more accurate and relevant agents from the start. You can refine any part of the configuration through conversation or combine it with manual edits for full control. [Learn more about the Agent Config Assistant in our documentation.](/carto-user-manual/ai-agents/agent-config-assistant)

{% endupdate %} {% update date="2026-03-27" tags="new,workflows" %} ## Viewer Mode for Workflows Workflows can now be shared with **Viewer Mode**, allowing editors to publish interactive workflows that other users can run without editing the canvas. This opens up new possibilities for delivering analytical tools and reports to stakeholders and business users. * **Viewer parameters**: Editors define which variables are exposed to viewers as configurable parameters, with custom display names and helper text. Supported types include Number, String, and the new **Geo** type, which lets viewers draw geographic features on a map. * **Viewer Result Output**: A new component that defines which node's output is displayed to viewers, giving editors full control over what results are visible. * **Viewer settings**: Granular controls over the viewer experience, including toggling the canvas visibility, SQL preview, data export, result caching, and more. [Learn more about Viewer Mode in our documentation](/carto-user-manual/workflows/viewer-mode). {% embed url="" %} {% endupdate %} {% update date="2026-03-19" tags="improvement,platform" %} ## Claude 4.6 models now available for AI Agents We've expanded the AI models available for AI Agents with the latest generation of Anthropic models. * **More CARTO-managed models:** Claude Opus 4.6 and Claude Sonnet 4.6 are now available out of the box with no additional configuration. * **Broader bring-your-own-model support:** You can now use Claude Opus 4.6 and Claude Sonnet 4.6 through any of our supported providers, including Vertex AI, AWS Bedrock, Azure OpenAI, Anthropic, Snowflake Cortex, and Databricks Serving Model. The 4.6 models deliver better performance across reasoning, tool usage, and complex geospatial workflows. Configure your models in **Settings > CARTO A**I — see the [CARTO AI documentation](/carto-user-manual/settings/carto-ai) for the full list of supported models and providers.

{% endupdate %} {% update date="2026-02-17" tags="improvement,platform" %} ## Additional AI models to power your Agents We've expanded the AI models available for AI Agents with more advanced models from Anthropic, Google, and OpenAI. * **More CARTO-managed models:** Claude Opus 4.5, Claude Sonnet 4.5, Gemini 3 Pro, and Gemini 3 Flash are now available out of the box with no additional configuration. * **Broader bring-your-own-model support:** You can now use Gemini 3, Claude Opus 4.5, and GPT-5.2 through any of our supported providers, including Vertex AI, Google AI Studio, Snowflake Cortex, Databricks Serving Model, AWS Bedrock, Azure OpenAI, OpenAI, and Anthropic. We recommend upgrading to the newest models available — you'll see a significant improvement in agent performance, reasoning, and tool usage. Configure your models in **Settings > CARTO AI** — see the [CARTO AI documentation](/carto-user-manual/settings/carto-ai) for the full list of supported models and providers.

{% endupdate %} {% update date="2026-02-09" tags="improvement,builder" %} ## AI Agents now create interactive charts [AI Agents](/carto-user-manual/ai-agents) can now generate and render interactive charts directly inside the conversation. Users can ask for data visualizations and see charts rendered inline — no need to leave the chat. Charts expand the way AI Agents can communicate insights, complementing map layers with statistical visualizations like bar charts for comparisons, line charts for trends, or histograms for distributions. Combined with other tools, AI Agents can query your data, analyze it, and present findings in the format that best fits the question. [Learn more about AI Agent tools in our documentation](/carto-user-manual/ai-agents/working-with-tools).

{% endupdate %} {% update date="2026-01-29" tags="new,platform" %} ## Introducing our new Command-line Interface We're excited to announce the [CARTO CLI](https://carto.com/blog/carto-cli-automateed-carto-management-build-for-ai-agents), which brings command line power to your CARTO organization. Manage Maps, Workflows, connections and credentials; transfer assets between organizations, and query your organization's activity data; all from the terminal! The CLI supports structured JSON output, non-interactive execution, and headless authentication, making it a natural interface to script and automate. To get started, head over to our [CARTO CLI documentation](/carto-for-agents/cli).

{% endupdate %} {% update date="2026-01-29" tags="improvement,workspace" %} ## Tracking activity data from public maps Public maps are the way to distribute geospatial data and insights across wider audiences outside your organization. From coverage maps to deforestation storytelling, many geospatial dashboards are making an impact on public websites thanks to CARTO. Starting now, CARTO administrators can measure that impact, and answer questions like: * **How many times my public maps have been viewed** * **Which are my most active public maps** * **How many exports from public maps last month...** We've automatically added to our [Activity Data](/carto-user-manual/settings/activity-data) the data coming from your public maps thanks to a robust, secure, event pipeline that can track millions of events coming from unauthenticated users. To get started, simply [export your Activity Data](/carto-user-manual/settings/activity-data) or [integrate it via API](/carto-user-manual/settings/activity-data#access-via-api).

{% endupdate %} {% update date="2026-01-20" tags="new,platform" %} ## New AI provider and LLM integrations to power your AI Agents CARTO now supports seven additional AI providers, expanding the AI and LLM integrations available to power **AI Agents**. Previously limited to **OpenAI** and **Google AI Studio**, you can now connect AI Agents to models hosted on your preferred cloud or data platform: * **Google Vertex AI**: Enterprise GCP deployments with service account authentication. * **Amazon Bedrock**: Claude models through AWS infrastructure. * **Snowflake Cortex**: AI models within your Snowflake environment. * **Databricks Model Serving**: Models through Databricks endpoints. * **Oracle Generative AI**: Access to models via OCI. * **Anthropic**: Direct access to Claude models. * **Azure OpenAI Service**: OpenAI models through Azure. These new integrations allow AI Agents to run on your preferred cloud or data platform, leverage existing cloud contracts, meet data residency requirements, and access the latest large language models available from each provider. Configure providers in **Settings > CARTO AI**. See the [CARTO AI documentation](/carto-user-manual/settings/carto-ai) for setup instructions.

{% endupdate %} {% update date="2026-01-14" tags="improvement,builder" %} ## CARTO Basemap labels now stay on top of your layers When using CARTO Basemaps, labels (like city and street names) now automatically appear on top of your map layers instead of being hidden underneath them. This makes it easier to read your maps, especially when working with multiple overlapping layers. You can still turn labels off in the basemap settings if you prefer a cleaner look.

{% endupdate %} {% update date="2026-01-12" tags="new,workflows,analytics-toolbox" %} ## H3-based isochrones powered by TravelTime A new capability is now available for generating **H3-based isochrones** using [TravelTime](https://docs.traveltime.com/api/reference/h3), expanding how accessibility and travel-time analysis can be performed in CARTO. This release introduces a new endpoint in the **Location Data Services (LDS) API** that leverages TravelTime’s H3 isochrone support. In addition, corresponding functions are available in the **Analytics Toolbox** (for [BigQuery](/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/lds#create_h3_isolines), [Snowflake](/data-and-analysis/analytics-toolbox-for-snowflake/sql-reference/lds#create_h3_isolines), [Databricks](/data-and-analysis/analytics-toolbox-for-databricks/reference/lds#create_h3_isolines) and [Redshift](/data-and-analysis/analytics-toolbox-for-redshift/sql-reference/lds#create_h3_isolines)), along with a new [Create H3 Isolines](/carto-user-manual/workflows/components/spatial-constructors#create-h3-isolines) component in **Workflows**, enabling low-code and programmatic access to this functionality. Customers can now generate H3-indexed isochrones directly, with support for the same configuration options provided by the underlying TravelTime API, including **departure time** and **transport mode**. Using H3 as the output format simplifies downstream analysis, aggregation, and visualization, particularly for workflows that already rely on hexagonal indexing. {% embed url="" %} {% endupdate %} {% update date="2026-01-07" tags="new,platform" %} ## Full support for new Databricks Spatial SQL functions and data types A new [Databricks connection](/carto-user-manual/connections/databricks) type is now generally available across all CARTO accounts, delivering deeper and more modern support for Databricks as a data warehouse and compute platform. This integration adopts **Databricks SQL Warehouses** as the sole compute resource, providing a serverless, cloud-native experience without the need to manage traditional compute clusters. It also leverages Databricks’ [**native spatial capabilities**](https://www.databricks.com/blog/introducing-spatial-sql-databricks-80-functions-high-performance-geospatial-analytics?utm_source=chatgpt.com), including the GEOMETRY data type and Spatial SQL functions documented by Databricks, enabling efficient storage and processing of spatial data directly in SQL without external libraries. Connectivity options include **Personal Access Tokens (PAT), M2M, and U2M integrations**, offering flexibility in how authentication and access are managed. Builder and Workflows fully support Databricks tables with geometry types out of the box, including query sources, SQL parameters, Location Data Services, and Create Builder Map workflows — no additional data preparation is required to work with spatial columns. The [**Analytics Toolbox**](/data-and-analysis/analytics-toolbox-for-databricks) now installs directly into the Databricks Unity Catalog with no external dependencies, simplifying governance and deployment. Older Databricks connection types remain available for existing accounts that used them previously. This release represents a significant step in CARTO’s support for major cloud data warehouse providers and extends CARTO’s capabilities for spatial analytics on modern data platforms.

{% endupdate %} {% update date="2025-12-29" tags="new,builder" %} ## Track map changes over time with Version history We've introduced **Version history** in Builder, giving you the ability to track and manage different versions of your maps over time. CARTO automatically saves versions as you work, and you can also manually save named versions to mark important milestones. You can view the full history of changes, restore any previous version to undo unwanted changes, or duplicate from a historical version to create variations without affecting the current map. Version history works seamlessly with collaborative maps—all changes are tracked with the collaborator's name and timestamp, providing a complete audit trail. When you publish a map, the published version is marked with a badge so you always know which version is live. [Learn more in our documentation](/carto-user-manual/maps/version-history).

{% endupdate %} {% update date="2025-12-12" tags="new,workflows" %} ## **New components to run spatial analytics techniques on embeddings from Geospatial Foundation Models** We’re introducing the **Analytics on Embeddings** extension package for **CARTO Workflows**, a new set of components that bring high-dimensional vector embedding analytics into spatial workflows. This extension enables users to analyze, cluster, compare, and visualize embedding representations (whether derived from geospatial foundation models, satellite data, or other spatial sources) directly within their Workflows pipelines. Key capabilities in this package include: * [**Change Detection**](/carto-user-manual/workflows/components/embedding-analytics#change-detection): Quantifies temporal changes in embedding vectors to monitor dynamics over time. * [**Clustering**](/carto-user-manual/workflows/components/embedding-analytics#clustering): Groups locations based on similarity in embedding space, with optional dimensionality reduction to improve performance. * [**Similarity Search**](/carto-user-manual/workflows/components/embedding-analytics#similarity-search): Identifies regions with similar spatial or contextual characteristics relative to one or more reference locations. * [**Visualization**](/carto-user-manual/workflows/components/embedding-analytics#visualization): Converts high-dimensional embeddings into RGB colors for intuitive mapping and pattern discovery. These components work seamlessly with embedding vectors stored as table columns and support integration with the [**Geospatial Foundation Models**](/carto-user-manual/workflows/components/google-pdfm-embeddings) extension, enabling richer insights from learned representations without leaving the low-code Workflows environment. {% endupdate %} {% update date="2025-12-09" tags="improvement,workspace" %} ## Manage developer credentials from the asset management table Superadmin users can now view and manage all developer credentials in their organization, including **API Access Tokens**, **SPA OAuth Clients**, and **M2M OAuth Clients**. From the Asset Management table of the settings, Superadmins now can: * Find credentials by type, name and owner * Transfer credentials to another user (only available for API Access Tokens and SPA OAuth Clients) * Delete credentials This improvement simplifies team collaboration by allowing credentials to be transferred between users seamlessly, preventing disruptions if the credential owner is unavailable or leaves. For more information, see our section on the [Superadmin role](/carto-user-manual/settings/users-and-groups/managing-user-roles#superadmin).

{% endupdate %} {% update date="2025-11-18" tags="improvement,workspace" %} ## Unified access to Data Observatory subscriptions and improved subscription management With this release, we’re making it simpler and more consistent for users to access and work with data from their Data Observatory subscriptions. Access to data has now been fully unified to always be via your own data warehouse connections. Additionally we've also improved the way Admin users can manage the organization's Data Observatory subscriptions from the Settings section in the CARTO Workspace. * We’ve unified access to the data from Data Observatory subscriptions to always be rom the end-user data warehouse connections. As announced earlier this year, we have **deprecated the Data Observatory tab in Data Explorer, Builder, and Workflows**. This tab previously exposed subscriptions only through a small set of connections (i.e. CARTO Data Warehouse and BigQuery US multi-region). Since all subscriptions are now available directly via data warehouse connections, the tab has been removed to avoid confusion. * The [Data Observatory section](/carto-user-manual/settings/data-observatory) in Settings has been significantly improved. It now serves as the central place to manage your organization’s subscriptions, showing to which data warehouse each subscription has been transferred, and allowing users to request new transfers so the data is available directly in their data warehouses.

{% endupdate %} {% update date="2025-11-18" tags="improvement,workspace" %} ## Starring data assets for quicker access Users are now able to star items at any level in the Data Explorer, including connections, projects/databases/schemas, and the data tables themselves. Simply click on the star icon next to any item in the Data Explorer and then use the *Starred only* filter to show just your starred items. This is especially helpful to users that have connections or data assets that are recurrently used in their maps and workflows. No more browsing the data tree until you find what you need! Your starred items are now also easily accessible from the "Add data source" flow in CARTO Builder and from the data sources panel in CARTO Workflows. To learn more about starring items and the Data Explorer in general, check out our [documentation](/carto-user-manual/data-explorer).

{% endupdate %} {% update date="2025-11-07" tags="improvement,builder" %} ## Integrate CARTO maps anywhere with the new authenticated embeds and reactive map events Embedding maps from CARTO in other webpages and applications just became exponentially easier and more powerful thanks to two additions to our platform: * **New methods for seamless and secure private embedding:** We added two new strategies to embed private maps securely, without having to publish the map or forcing the users to login in a different tab or browser. Developers can also re-use existing authorization in their applications. [Learn more about private embedding strategies](/carto-user-manual/maps/sharing-and-collaboration/embedding-maps#private-embedding). * **Build bi-directional interactive experiences with our embedded events:** Embedded maps from CARTO now send `postMessage` events every time something changes in the map. This allows the parent application to react, creating bi-directional interactive experiences when combined with our embed URL parameters. [Learn more about embedding events](/carto-user-manual/maps/sharing-and-collaboration/embedding-maps#listening-to-events-from-embedded-maps). We're excited to see where you will embed your next CARTO map!

{% endupdate %} {% update date="2025-11-06" tags="new,builder" %} ## New map interaction tools for AI Agents AI Agents can now interact directly with your maps through two new tools: **Dynamic marker placement**: Ask the AI Agent to mark specific locations, and it will instantly place markers on your map. Simply provide an address, place name, or coordinates—the agent handles geocoding and placement automatically. **Spatial filtering by area**: The AI Agent can define custom areas of interest to filter your data dynamically. When an area is set, all map widgets and layers update automatically to show only data within that region. These tools enable your AI Agent to provide immediate visual context and perform focused analysis on specific geographic areas without manual configuration. [Learn more in our documentation](/carto-user-manual/ai-agents/working-with-tools#map-tools).

{% endupdate %} {% update date="2025-10-08" tags="new,builder" %} ## Introducing Agentic GIS in CARTO: making spatial insights available to everyone We are incredibly excited to announce new features that bring enterprise-grade geospatial agentic experiences to CARTO. * **Introducing AI Agents in Builder:** [CARTO AI Agents](/carto-user-manual/ai-agents) (now in General Availability) provide a conversational interface in your maps where your end users can get instant and actionable geospatial insights through natural language. * **AI Agents can now query sources, generate layers and more:** We've added a ton of exciting capabilities that allow agents to reason and perform geospatial analysis autonomously. * **Integrate Workflows as tools for your AI Agents:** From building operational dashboards to running complex analyses, your AI Agent can be supercharged with your own custom workflows [enabled as MCP tools](/carto-user-manual/workflows/workflows-as-mcp-tools). * **Evolved experience to tailor your Agent:** You can now reference tools, sources, and other context available in the map when customizing your agent. * **Use your own AI models:** [Configure your own AI models](/carto-user-manual/settings/carto-ai) and maintain total control over the AI technology used. Supported providers include Google Gemini and Open AI, with others coming soon. With CARTO you can now create and share access to powerful geospatial AI Agents tailored to your specific needs. Combine your custom prompt instructions with CARTO's built-in geospatial intelligence and your own workflows, and **build trustworthy AI solutions that make complex geospatial analysis accessible to any user within your organization**. Get started today by [enabling CARTO AI in your organization](/carto-user-manual/settings/carto-ai). And learn more about Agentic GIS in our [announcement blog post](https://carto.com/blog/agentic-gis-bringing-ai-driven-spatial-analysis-to-everyone)!

{% endupdate %} {% update date="2025-10-08" tags="new,workflows" %} ## Turn your AI Agents into geospatial experts with CARTO MCP Server CARTO now supports the **Model Context Protocol (MCP)**, a standard that enables AI Agents to interact with external tools and data sources. With the new **CARTO MCP Server**, organizations can now expose their own geospatial [Workflows as MCP Tools](/carto-user-manual/workflows/workflows-as-mcp-tools) that any MCP-compliant agent can use. This release allows GIS teams to design custom workflows in CARTO—defining inputs, outputs, and logic specific to their spatial problems—and make them available to AI Agents through the MCP Server. Each tool includes detailed metadata following the MCP specification, ensuring interoperability across agentic AI environments. By combining Workflows and the MCP Server, organizations can empower AI Agents to perform advanced spatial analysis, automate geospatial decision-making, and connect AI-driven applications to their cloud data infrastructure. {% embed url="" %} {% endupdate %} {% update date="2025-09-30" tags="new,workflows" %} ## Territory Balancing and Location Allocation components in Workflows CARTO's new [Territory Planning Extension Package](/carto-user-manual/workflows/components/territory-planning) for Workflows has been built to power location allocation and territory balancing directly within CARTO and your data warehouse, this extension helps analysts and planners create fair, efficient, and data-driven territory strategies. * [Territory Balancing](https://docs.carto.com/carto-user-manual/workflows/components/territory-planning#territory-balancing) – Divide an area into continuous, optimized territories that are balanced according to a chosen metric (e.g. consumer demand or other business KPIs), while keeping each territory internally cohesive. Learn more about this new capability following this [tutorial](https://academy.carto.com/creating-workflows/step-by-step-tutorials/optimizing-workload-distribution-through-territory-balancing). * [Location Allocation](https://docs.carto.com/carto-user-manual/workflows/components/territory-planning#location-allocation) – Find the optimal locations to open facilities (stores, warehouses, service hubs) and efficiently assign demand points (retail stores, populated regions) to them, minimizing costs or maximizing coverage. Take a look at this [tutorial](https://academy.carto.com/creating-workflows/step-by-step-tutorials/transforming-telco-network-management-decisions-with-location-allocation) to learn more!. This extension package is currently available for Google BigQuery and Snowflake.

{% endupdate %} {% update date="2025-08-28" tags="improvement,workspace" %} ## Improved flow for deleting connections We've added a new option for users deleting connections so that all maps, workflows, tokens, etc. using the connection are updated to use another connection. Previously, users had to either update each asset individually or delete the connection along with all assets using it. This new option vastly facilitates migrating from one connection to another, which is a common case when upgrading authentication types (changing from username/password to key pair or OAuth, for example). Alternatively, users can still choose to delete the connection along with all assets that use it. For more information, see our article on [deleting connections](/carto-user-manual/connections/deleting-a-connection).

{% endupdate %} {% update date="2025-08-28" tags="improvement,workspace" %} ## Improvements to importing geospatial data into cloud data warehouses Recent updates have enhanced the experience of importing geospatial data into cloud data warehouses, with improvements in performance, scalability, and raster support. Import operations now run faster thanks to a new, optimized process. The maximum supported file size has also been raised from **1GB to 5GB**, addressing a very frequent need when working with large geospatial datasets. Raster-processing capabilities have been extended in **BigQuery and Snowflake**, supporting the import of non-COG GeoTIFF rasters into warehouse tables following the [Raquet specification](https://github.com/CartoDB/raquet?utm_source=chatgpt.com). This removes the strict preparation steps previously required for Cloud Optimized GeoTIFFs, making the process considerably simpler. Combined with the higher size limit, these updates provide a more efficient way for customers to bring raster data into their cloud environment. {% embed url="" %} {% endupdate %} {% update date="2025-08-27" tags="improvement,builder" %} ## **Drag and drop reordering of properties in Table and Interactions** We've introduced the ability to reorder the properties shown in the Table widget and Tooltip via simple drag and drop functionality. Until now, users could configure which properties to show, but changing the order they are presented often meant clearing the setup and starting over again. With this enhancement, it’s easier than ever to customize how data is displayed, improving readability and enabling tailored views for different audiences.

{% endupdate %} {% update date="2025-08-12" tags="new,workflows" %} ## **Control Components in Workflows: Conditional Split & Success/Error Split** We’ve added two new [control components](/carto-user-manual/workflows/components#control) to CARTO Workflows that make it easier to control how your workflows execute and respond to different scenarios. * [**Conditional Split**](/carto-user-manual/workflows/components/control#conditional-split) – Direct your workflow into **If** and **Else** branches based on a condition you define. Build the condition with a simple UI (column + aggregation + operator + value) or use a custom SQL expression for more complex logic.\ Some usage examples: * “If the **count of underserved households** in a service area is greater than 500, trigger a fiber expansion workflow; otherwise plan for wireless coverage.” * “If the **average property value** in a high-risk flood zone is above $1M, apply the high-risk pricing model; otherwise, use the standard pricing model.” * [**Success/Error Split**](/carto-user-manual/workflows/components/control#success-error-split) – Branch execution depending on whether the previous step ran successfully or failed.\ Some usage examples: * “If network quality metrics fail to load, send an alert; otherwise continue with churn prediction.” * “If address geocoding fails, switch to a backup geocoder; otherwise proceed with claims analysis.” These components let you build workflows that adapt to your data, add robust error-handling, and reduce the need for manual monitoring — helping teams act faster on reliable insights. {% embed url="" %} {% endupdate %} {% update date="2025-08-05" tags="improvement,workspace" %} ## **Separation of working locations for improved data governance** We have introduced a clearer separation of datasets/schemas that CARTO creates and manages in connected data warehouses. This change improves data governance and prevents persistent objects from being stored alongside temporary workflow tables. **New locations per connection:** * **CARTO temp location** – stores only temporary tables created during workflow execution. * **CARTO Workspace location** – stores persistent objects related to workflows, such as API stored procedures and imported files. * **CARTO Extensions location** – stores Extension Package resources, including shared stored procedures and metadata. Only for BigQuery and Snowflake. **Additional notes:** * For connections shared requiring Viewer Credentials, `carto_temp_` and `carto_workspace_` are created per user. * The Extensions location is always shared across all users in a connection, ensuring consistent access to installed packages. * Default names can be overridden in the connection’s advanced options. * Locations are automatically created as needed (`CREATE IF NOT EXISTS`). This update applies to all supported warehouses. Find specific documentation on the *Advanced settings* section for each warehouse in the [Connections](/carto-user-manual/connections) section of the documentation.

{% endupdate %} {% update date="2025-07-29" tags="new,builder" %} ## Support for adding sources without associated layer in Builder Editor users can now add data sources to a Builder map **without displaying associated layers**. These sources can be used to power widgets, SQL parameters, and even be used by AI Agents to generate insights. This is especially useful when a dataset is needed for interactivity or calculations, but not for visualization. It helps keep your maps cleaner, more focused, and easier to maintain.

{% endupdate %} {% update date="2025-07-17" tags="new,workspace" %} ## Organization Governance Settings for Admins Admins can now set up custom governance policies through the new **Governance** section in Settings. These controls give you the tools to manage data access, sharing, and feature usage across your organization with precision. Control who can create new Data Warehouse connections with granular settings for providers and authentication methods. Manage connection sharing, disable the CARTO Data Warehouse, and fine-tune Builder features like Download PDF report, export viewport data, and more! To see all the new settings, check our section on [Organization Governance](/carto-user-manual/settings/organization-governance).

{% endupdate %} {% update date="2025-07-15" tags="improvement,builder" %} ## Support for Widgets linked to Raster sources in Builder You can now use Widgets with raster sources in Builder — just like you already can with vector sources. This improvement allows for richer exploration and analysis of raster sources stored in your data warehouse directly from the map. Use the Formula Widget to calculate metrics like tree coverage in your current view. Leverage Category and Pie Widgets to list distinct values in your raster layer, or use the Histogram Widget to explore data distributions such as precipitation. These widgets can also be used for filtering, letting you interactively refine what’s shown on the map and extract insights more effectively. [Learn more in our documentation](/carto-user-manual/maps/widgets).

{% endupdate %} {% update date="2025-07-08" tags="new,workspace" %} ## Audit all queries with the CARTO SQL audit trails When a map or workflow is opened, CARTO launches a set of SQL queries to your data warehouse to visualize your data and run your analysis. And from now on, each of those SQL queries will contain a **rich audit trail** in the form of SQL comments at the beginning or the end of the query. This audit information allows data warehouse administrators to monitor CARTO and answer questions such as: *How many queries did CARTO run in a period of time? Which workflows or maps have processed more data? What are some common performance or cost patterns?* To start using this information in your audits, check our [Auditing SQL queries documentation](/carto-user-manual/connections/auditing-sql-queries-from-carto).

{% endupdate %} {% update date="2025-06-30" tags="improvement,workflows" %} ## Collaborative edition in Workflows Workflows now supports [**collaborative editing**](/carto-user-manual/workflows/sharing-workflows#editor-collaboration) for teams. Editors can share workflows with their entire organization, SSO groups, or specific users to enable collaborative development. This feature eliminates the need to duplicate workflows for minor changes, ensuring teams work from a single, consistent source of truth. Asynchronous editing with a request/approval model reduces conflicts while supporting smooth, coordinated teamwork. Editor collaboration makes it easier for organizations to use Workflows at scale and promotes more frequent, effective use across teams. {% embed url="" %} {% endupdate %} {% update date="2025-06-25" tags="new,builder" %} ## Cross-filtering multiple data sources from map widgets You can now use a **single widget to filter multiple sources** in your Builder map as long as they share the same field. Previously, widgets could only filter a single source. Now, widgets like Category or Time Series will update multiple sources and their related elements (like other widgets or layers) when the filtering property matches. This is especially useful when working with complementary datasets. For example, filtering both sales and demographic data by region to uncover richer insights. Learn more in our [Widget Behavior](/carto-user-manual/maps/widgets#widget-behavior) section of the documentation.

{% endupdate %} {% update date="2025-06-19" tags="improvement,builder,carto-for-developers" %} ## Custom aggregation support on Category, Pie and Time Series Widget You can now define **custom aggregation** operations directly in [**Category**](/carto-user-manual/maps/widgets/category-widget), [**Pie**](/carto-user-manual/maps/widgets/pie-widget), and [**Time Series**](/carto-user-manual/maps/widgets/time-series-widget) widgets, previously only available in Formula widgets. This enhancement enables more advanced use cases by allowing tailored **SQL expressions** within the widget configuration, giving users greater control over how insights are calculated and displayed. Custom aggregations are supported in both **CARTO Builder** and the **CARTO Developer framework** for programmatically creating widgets.\ \ Learn more in the [Widget*s*](/carto-user-manual/maps/widgets) section of Builder or the CARTO for Developers [technical reference](/carto-for-developers/reference/carto-widgets-reference).

{% endupdate %} {% endupdates %} # Q4 2026 New features and improvements introduced from October to December 2026 {% updates %} {% update date="2026-10-07" tags="new,ai-agents" %} ## AI Agents can refresh the data on your map Ask an AI Agent to run an [MCP Tool](/carto-user-manual/workflows/workflows-as-mcp-tools) that changes your data and the map now updates by itself. The layers, the widgets and the tables all show the new numbers, nobody has to reload the page, and your conversation with the Agent carries on. For example, ask an Agent to rebuild the drive-time areas around your stores for a longer drive, or to score your candidate sites again after you change what matters most. The new result lands on the map you are already looking at. Learn more in the [AI Tools Reference](/carto-user-manual/ai-agents/ai-tools-reference) documentation.

{% endupdate %} {% endupdates %} # Q3 2026 New features and improvements introduced from July to September 2026 {% updates %} {% update date="2026-09-23" tags="new,platform" %} ## Claude 5, Gemini 3.8 and GPT-6 Astra are now in CARTO CARTO AI now offers the newest generation of models, including Claude Opus 5.5 within a day of its launch. The CARTO-managed set adds `claude-sonnet-5`, our new default for geospatial use cases, `claude-opus-5.5`, our most capable model for the hardest geospatial reasoning, and `gemini-3.8-flash` for fast, high-volume interactions. If you bring your own provider, the newest models are available too. `claude-fable-5.1`, `claude-opus-5` and `claude-sonnet-5` run on Anthropic, Bedrock and Vertex AI, with `claude-opus-5.5` also on Vertex AI. Claude 5 models are available on Databricks as well. `gemini-3.8-flash` runs on Vertex AI, Google AI Studio and Databricks, and `gpt-6-astra` on OpenAI. Learn more in the [CARTO AI settings](/carto-user-manual/settings/carto-ai) documentation.

{% endupdate %} {% update date="2026-09-07" tags="new,platform" %} ## Deploy CARTO Self-Hosted on any cloud CARTO Self-Hosted is now provider agnostic. Alongside AWS, Google Cloud, Azure, and Oracle Cloud, any infrastructure that provides **standard Kubernetes**, a **PostgreSQL** database, and **S3-compatible object storage** can run a complete CARTO deployment: regional providers such as OVHcloud or Scaleway, **sovereign clouds** operated within national borders, and **private clouds** or on-premises platforms with S3-compatible storage such as Ceph. This is possible because CARTO Self-Hosted now works with any S3-compatible object storage, so it adapts to the infrastructure you already run. Configuration follows the same steps as before, with a couple of extra fields for your storage endpoint. This opens CARTO to organizations whose data residency or sovereignty requirements call for infrastructure in a specific jurisdiction or in their own data center. Available since CARTO Self-Hosted [2026.8.11](https://docs.carto.com/whats-new/pages/bDddXkUezz5UkejnQDMd#2026.8.11). Learn more in our [Object Storage prerequisites](/carto-self-hosted/planning/prerequisites/object-storage) and [Configure your own buckets](/carto-self-hosted/configuration/data-and-storage/configure-your-own-buckets) documentation.

{% endupdate %} {% update date="2026-07-02" tags="builder,improvement" %} ## Single-select mode for text parameters Text parameters in Builder can now be set to **single value** instead of always allowing multiple selections. Viewers pick exactly one option from a radio list, and you decide which value is selected by default. Single-select fits any map that should answer for one thing at a time: a single product line, region, store, audience segment, or scenario in a what-if comparison. The viewer picks one option and the map returns one clear, correct result. Learn more in the [Text parameter](/carto-user-manual/maps/sql-parameters/text-parameter) documentation.

{% endupdate %} {% endupdates %} # Q2 2026 New features and improvements introduced from April to June 2026 {% updates %} {% update date="2026-06-29" tags="new,builder" %} ## Labels for polygons and lines in Builder You can now add text labels directly to polygon and line layers, not just points. Turn labels on from the **Labels** section of the layer panel and choose the column to display. CARTO places each label automatically, at the center of every polygon and along the middle of every line. For lines, you can also pick a unique ID column so a feature that crosses several tiles, like a long road, shows a single label instead of one per tile. Learn more in our [Layers documentation](/carto-user-manual/maps/layers#labels).

{% endupdate %} {% endupdates %} # Q1 2026 New features and improvements introduced from January to March 2026 {% updates %} {% update date="2026-03-30" tags="new,carto-for-developers" %} ## Build AI-first spatial apps with CARTO Agentic Tools for developers Building AI-powered apps with geospatial capabilities just got a lot easier. We're releasing `@carto/agentic-deckgl`, an open-source TypeScript library built on [CARTO + deck.gl](https://carto.com/blog/modern-spatial-app-development-carto/) that lets any AI Agent create and style map layers, run spatial analytics, and interact with the map through natural language — with one npm install. It's framework-agnostic, includes Zod-validated tool definitions, a geospatial system prompt builder, and SDK converters for major AI frameworks. The library gives AI Agents full control over the map experience: creating and styling vector tile, H3, GeoJSON, and raster layers from any CARTO data source; navigating the globe with smooth transitions; switching basemaps; placing and managing markers; applying spatial filters from user-drawn areas or analytical workflows; and managing widgets, visual effects, and layer ordering. Learn more about this new library in our [product announcement](https://carto.com/blog/carto-agentic-tools-for-developers/).

{% endupdate %} {% update date="2026-03-30" tags="new,builder" %} ## Create AI Agents through conversation with the new Configuration Assistant Creating AI Agents just got significantly easier. The new **Agent Configuration Assistant** lets you design, set up, and iterate on your agents using natural language. Instead of manually defining instructions, selecting tools, and configuring capabilities step by step, you can now **simply describe what your agent should do**. The Assistant generates a complete configuration for you — including the use case, structured instructions, model selection, tool setup, capabilities, and a tailored introduction message. The Assistant is context-aware, meaning its recommendations are grounded in your actual map. It understands your datasets, layers, widgets, and available tools, helping you create more accurate and relevant agents from the start. You can refine any part of the configuration through conversation or combine it with manual edits for full control. [Learn more about the Agent Config Assistant in our documentation.](/carto-user-manual/ai-agents/agent-config-assistant)

{% endupdate %} {% endupdates %} # Q4 2025 New features and improvements introduced from October to December 2025 {% updates %} {% update date="2025-12-29" tags="new,builder" %} ## Track and restore previous versions of your map We've introduced **Version history** in Builder, giving you the ability to track and manage different versions of your maps over time. CARTO automatically saves versions as you work, and you can also manually save named versions to mark important milestones. You can view the full history of changes, restore any previous version to undo unwanted changes, or duplicate from a historical version to create variations without affecting the current map. Version history works seamlessly with collaborative maps—all changes are tracked with the collaborator's name and timestamp, providing a complete audit trail. When you publish a map, the published version is marked with a badge so you always know which version is live. [Learn more in our documentation](/carto-user-manual/maps/version-history).

{% endupdate %} {% update date="2025-11-06" tags="new,builder" %} ## New map interaction tools for AI Agents AI Agents can now interact directly with your maps through two new tools: * **Dynamic marker placement**: Ask the AI Agent to mark specific locations, and it will instantly place markers on your map. Simply provide an address, place name, or coordinates—the agent handles geocoding and placement automatically. * **Spatial filtering by area**: The AI Agent can define custom areas of interest to filter your data dynamically. When an area is set, all map widgets and layers update automatically to show only data within that region. These tools enable your AI Agent to provide immediate visual context and perform focused analysis on specific geographic areas without manual configuration. [Learn more in our documentation](/carto-user-manual/ai-agents/working-with-tools#map-tools).

{% endupdate %} {% update date="2025-10-08" tags="new,workflows" %} ## Turn your AI Agents into geospatial experts with CARTO MCP Server CARTO now supports the **Model Context Protocol (MCP)**, a standard that enables AI Agents to interact with external tools and data sources. With the new **CARTO MCP Server**, organizations can now expose their own geospatial [Workflows as MCP Tools](/carto-user-manual/workflows/workflows-as-mcp-tools) that any MCP-compliant agent can use. This release allows GIS teams to design custom workflows in CARTO—defining inputs, outputs, and logic specific to their spatial problems—and make them available to AI Agents through the MCP Server. Each tool includes detailed metadata following the MCP specification, ensuring interoperability across agentic AI environments. By combining Workflows and the MCP Server, organizations can empower AI Agents to perform advanced spatial analysis, automate geospatial decision-making, and connect AI-driven applications to their cloud data infrastructure. {% embed url="" %} {% endupdate %} {% endupdates %} # Q3 2025 New features and improvements introduced from July to September 2025 {% updates %} {% update date="2025-09-30" tags="new,workflows" %} ## Territory Balancing and Location Allocation components in Workflows CARTO's new [Territory Planning Extension Package](/carto-user-manual/workflows/components/territory-planning) for Workflows has been built to power location allocation and territory balancing directly within CARTO and your data warehouse, this extension helps analysts and planners create fair, efficient, and data-driven territory strategies. * [Territory Balancing](https://docs.carto.com/carto-user-manual/workflows/components/territory-planning#territory-balancing) – Divide an area into continuous, optimized territories that are balanced according to a chosen metric (e.g. consumer demand or other business KPIs), while keeping each territory internally cohesive. Learn more about this new capability following this [tutorial](https://academy.carto.com/creating-workflows/step-by-step-tutorials/optimizing-workload-distribution-through-territory-balancing). * [Location Allocation](https://docs.carto.com/carto-user-manual/workflows/components/territory-planning#location-allocation) – Find the optimal locations to open facilities (stores, warehouses, service hubs) and efficiently assign demand points (retail stores, populated regions) to them, minimizing costs or maximizing coverage. Take a look at this [tutorial](https://academy.carto.com/creating-workflows/step-by-step-tutorials/transforming-telco-network-management-decisions-with-location-allocation) to learn more!. This extension package is currently available for Google BigQuery and Snowflake.

{% endupdate %} {% endupdates %} # Q2 2025 New features and improvements introduced from April to June 2025 {% updates %} {% update date="2025-06-30" tags="improvement,workflows" %} ## Collaborative edition in Workflows Workflows now supports [**collaborative editing**](/carto-user-manual/workflows/sharing-workflows#editor-collaboration) for teams. Editors can share workflows with their entire organization, SSO groups, or specific users to enable collaborative development. This feature eliminates the need to duplicate workflows for minor changes, ensuring teams work from a single, consistent source of truth. Asynchronous editing with a request/approval model reduces conflicts while supporting smooth, coordinated teamwork. Editor collaboration makes it easier for organizations to use Workflows at scale and promotes more frequent, effective use across teams. {% embed url="" %} {% endupdate %} {% update date="2025-06-25" tags="new,builder" %} ## Cross-filtering multiple data sources from map widgets You can now use a **single widget to filter multiple sources** in your Builder map as long as they share the same field. Previously, widgets could only filter a single source. Now, widgets like Category or Time Series will update multiple sources and their related elements (like other widgets or layers) when the filtering property matches. This is especially useful when working with complementary datasets. For example, filtering both sales and demographic data by region to uncover richer insights. Learn more in our [Widget Behavior](/carto-user-manual/maps/widgets#widget-behavior) section of the documentation.

{% endupdate %} {% update date="2025-05-30" tags="improvement,carto-for-developers" %} ## Integrate CARTO Builder maps at scale in your custom applications using fetchMap Developers have now access to an extended set of tools to bring maps from CARTO Builder into their applications, **allowing collaboration with non-developer users** who can be in charge of the cartography, or simply, accelerating the styling process of layers. Key points are: * Non-developers can prototype and build [maps in Builder](/carto-user-manual/maps) as usual. * Developers use `fetchMap` to retrieve maps from CARTO into their code. * The map properties can then be integrated and customized, to perfectly blend in your application. This includes **layers, legend,** and **interactions** (tooltips, popups, hover...). * Works with private and public maps. Learn more about the improvements to fetchMap in our [technical reference](/carto-for-developers/reference/fetchmap), or check [how we built our example](/carto-for-developers/examples#fetchmap). {% embed url="" %} {% endupdate %} {% update date="2025-05-29" tags="new,workspace" %} ## Support for sharing maps with Guest viewers We've introduced a new user role, [**Guest viewer**](/carto-user-manual/settings/users-and-groups/managing-user-roles#guest-viewers), designed for organizations that want to share maps with external partners, clients or collaborators. Users with this new role can only see the maps that have been explicitly shared with them, which improves collaboration with external users as it removes the need to make sensitive maps public. As these are authenticated users, Editors can grant or revoke Guest viewer access to any map at any point, while Admins can view a complete audit trail of their activity. For more information, head to our section on [Guest viewers](/carto-user-manual/settings/users-and-groups/managing-user-roles#guest-viewers).

{% endupdate %} {% update date="2025-05-26" tags="new,workflows,analytics-toolbox" %} ## **Routing Matrix support in the Analytics Toolbox, Workflows, and LDS API** CARTO now supports computing **travel time and distance origin–destination matrices** using third-party APIs from TravelTime and TomTom. New functions in the Analytics Toolbox allow users to build routing matrices with full control over input parameters, enabling accurate and optimized travel time analysis. This capability is also available through a new component in Workflows, providing a low-code way to integrate travel time data into broader spatial processes. A new endpoint in the **Location Data Services (LDS) API** has been introduced to support this functionality across the Analytics Toolbox and Workflows, ensuring robust and scalable access to routing services. The new functions and components are available in [Workflows](/carto-user-manual/workflows/components/spatial-constructors#create-routing-matrix) and the Analytics Toolbox for [BigQuery](/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/lds#create_routing_matrix), [Snowflake](/data-and-analysis/analytics-toolbox-for-snowflake/sql-reference/lds#create_routing_matrix) and [Redshift](/data-and-analysis/analytics-toolbox-for-redshift/sql-reference/lds#create_routing_matrix). {% embed url="" %} {% endupdate %} {% update date="2025-05-13" tags="new,builder" %} ## Enhanced collaboration with User Comments now available in Builder You can now collaborate directly in your Builder maps using **Comments**. Add notes tied to specific locations, start threaded discussions, and tag teammates to bring everyone into the conversation—right where decisions are made. Built for collaboration, Comments help reduce back-and-forth, speed up decision-making, and turn your maps into **collaborative mapping experiences**. Ready to start? Check our [documentation](/carto-user-manual/maps/sharing-and-collaboration/comments) to learn more.

{% endupdate %} {% update date="2025-05-12" tags="new,workflows" %} ## Automate the creation of maps with the new Create Builder Map component in Workflows A new component is now available in CARTO Workflows to automate the creation and update of Builder maps. With support for three modes—**Create copy**, **Overwrite**, and **Update**—this component gives users full control over how maps are generated and maintained as part of a workflow. This functionality allows users to integrate map generation into larger geospatial processes, ensuring that maps stay up to date with the latest analytical results. Whether you're building templated workflows, maintaining a dashboard, or running scheduled processes, this component helps reduce manual steps and ensures consistency across your visual outputs. Check the [documentation](/carto-user-manual/workflows/components/input-output#create-builder-map) to get started. {% embed url="" %} {% endupdate %} {% update date="2025-04-03" tags="new,carto-for-developers" %} ## New developer framework-agnostic widgets for Tileset and Raster sources Developers building custom, scalable geospatial apps with CARTO can now add custom charts and widgets on top of their **tileset** and **raster** sources, enriching their application with additional GPU-powered **filtering** capabilities. These widgets have the same features as all our developer widgets: * **Fully-customizable:** using flexible data models and your own UI charting library. * **Easily sync your widgets** with the deck.gl map, and seamlessly use widgets to **filter**. * **Framework-agnostic, with minimal dependencies:** built with pure JS and Typescript, it integrates nicely in your own stack (Angular, React, Vue...). Use cases include land use treemap charts, NDVI average scorecards, or frequency histograms over huge tilesets with millions of points, and everything in between... Get creative! Ready to get started? Check the [technical reference](/carto-for-developers/reference/carto-widgets-reference) or play with our [examples](/carto-for-developers/examples)!

{% endupdate %} {% update date="2025-04-03" tags="improvement,workspace" %} ## View all assets in your organization with the new Superadmin role We have introduced a new user role –[Superadmin](/carto-user-manual/settings/users-and-groups/managing-user-roles#superadmin)– capable of viewing and managing all assets (Maps, Workflows and Connections) in the organization, regardless of who owns them or their visibility settings. This new role will help facilitate the administration and governance of large organizations with many users and many assets: * Delete and transfer assets in bulk * Filter assets by owner * View detailed asset relationships, such as the Connection used by a Workflow. For more information, see our section on the [Superadmin role](/carto-user-manual/settings/users-and-groups/managing-user-roles#superadmin-role).

{% endupdate %} {% endupdates %} # Q1 2025 New features and improvements introduced from January to March 2025 {% updates %} {% update date="2025-03-19" tags="improvement,builder" %} ## Control layer presence in Builder’s map layer list Editor users can now manage the presence of a layer in the map layer list directly from the [Legend](/carto-user-manual/maps/legend) tab in Builder. Previously, it was only possible to show or hide a layer’s legend. With this update, you now have full control over whether a layer itself should appear in the map layer list — what end-users see and interact with during map exploration.

{% endupdate %} {% update date="2025-03-19" tags="new,carto-for-developers" %} ## Manage your maps, workflows, and connections at scale with our new Resources APIs As organizations expand their usage of CARTO and *break the GIS data silo* using cloud-native maps and workflows, it becomes important to have the right tools to manage all resources at scale. This is why, starting today, all users in CARTO have access to a **new set of API endpoints where they can programmatically list and delete their maps, workflows, and connections**. Additionally, to empower *Superadmins* on their journey to enable CARTO for large organizations, we're exposing the following functionality via the new APIs: * List all the maps, workflows, and connections in a CARTO organization * Bulk delete of multiple assets with a single API request * Transfer the ownership of an asset (map, workflow, or connection) to another user Ready to scale up? Head over to our [API reference](/carto-for-developers/reference/carto-api) to get started.

{% endupdate %} {% update date="2025-03-13" tags="new,workspace" %} ## Connect to Databricks using OAuth authentication Users can now connect to their Databricks account using OAuth authentication, with both Machine-to-Machine (M2M) and User-to-Machine (U2M) authentication flows supported! This adds an extra layer of security for Databricks users since OAuth tokens are automatically refreshed by default and do not require the direct management of the access token. For these reasons, Databricks is strongly recommending its users to choose OAuth over Personal Access Tokens. Want to learn more? head over to our [section on Databricks connections](/carto-user-manual/connections/databricks).

{% endupdate %} {% update date="2025-02-27" tags="new,builder" %} ## Visualize rasters in Builder, directly from your data warehouse Raster visualization is now available in Builder, marking a major milestone in CARTO’s end-to-end support for raster data. With this release, you can seamlessly import, analyze, and visualize raster datasets stored in Google BigQuery and Snowflake—all within CARTO. This new capability unlocks powerful use cases, allowing you to explore and analyze data at scale, seamlessly within your cloud environment, without additional data movement. Interesting in learning more? [Check our documentation](/carto-user-manual/maps/layers/raster).

{% endupdate %} {% update date="2025-02-20" tags="new,builder" %} ## Introducing AI Agents for maps - now available in Public Preview We’re excited to announce the Public Preview of CARTO [AI Agents](/carto-user-manual/ai-agents), designed to make interacting with your maps in Builder more intuitive and dynamic. With AI Agents, users can seamlessly zoom to specific regions based on conversational input, explore map details, and apply filters using widgets—all through a natural language interface. ✨ Stay tuned—this is just the beginning. We’re already working on making AI Agents faster, smarter, and more powerful to elevate your mapping experience even further.

{% endupdate %} {% update date="2025-02-18" tags="new,workflows" %} ## Expanding CARTO for Databricks: Location Data Services & Data Enrichment We’re introducing **Location Data Services (LDS) support** and **new data enrichment components** in **CARTO for Databricks**, enabling more seamless geospatial analysis across different user roles and workflows. * **Location Data Services (LDS) Support**: Now available in both the [**Analytics Toolbox for Databricks**](/data-and-analysis/analytics-toolbox-for-databricks) and as **Workflows components**.\ Users can perform [**geocoding**](/carto-user-manual/workflows/components/spatial-constructors#st-geocode)**,** [**routing**](/carto-user-manual/workflows/components/spatial-constructors#create-routes)**, and** [**isoline**](/carto-user-manual/workflows/components/spatial-constructors#create-isolines) calculations via CARTO’s standard providers. The Analytics Toolbox enables direct use within **Databricks notebooks and SQL workflows**, while CARTO Workflows provides a **low-code interface**, integrating LDS into broader spatial analysis pipelines. LDS usage is subject to **CARTO licensing and quotas**, but users can also bring their own provider credentials, just as with other data warehouses. * **Data Enrichment Components**: These new Workflows components simplify use cases like demographic enrichment, POI data integration, and trade area analysis. Users can enhance datasets with information from **CARTO’s Data Observatory** or their **own geospatial sources**, whether structured as **spatial indexes, points, or polygons**. By embedding enrichment within **CARTO Workflows**, users can more easily integrate this step into their existing analysis. These updates further **reduce complexity** for Databricks users working with spatial data. Data scientists can leverage LDS functions directly within their Databricks environment, while Workflows opens up more advanced spatial analysis to less technical users. By bringing LDS and enrichment into CARTO Workflows, we make it easier to build complete geospatial pipelines without writing custom code. {% embed url="" %} {% endupdate %} {% update date="2025-02-06" tags="new,integrations" %} ## Bringing cloud-native spatial analytics to your desktop GIS with the new CARTO QGIS Plugin The new [CARTO QGIS Plugin](/data-and-analysis/carto-qgis-plugin) allows you to access, visualize, and edit spatial data from leading cloud data warehouses directly within QGIS. With this plugin, you can seamlessly check out data from Google BigQuery, Snowflake, Databricks, AWS Redshift, and PostgreSQL, edit it within QGIS, and commit changes back to your data warehouse—all powered by the CARTO platform. Simply connect your cloud data warehouse to CARTO, install the QGIS plugin, and gain full control over your geospatial data in a familiar GIS environment. This enables smooth workflows for spatial data management, enrichment, and analysis while ensuring your data remains centralized and up to date in your cloud ecosystem.

{% endupdate %} {% update date="2025-02-03" tags="new,workspace" %} ## Connect to Snowflake using Key-pair authentication Snowflake users can now connect to their Data Warehouse using **Key-pair authentication**! This is a much more secure alternative to basic username/password authentication as it is highly resistant to brute-force attacks, eliminates password management complexities, and can be easily used as the authentication mechanism for scripts and applications. We've also added support for Key-pair rotation, enabling users to update the private key of Key-pair connections they own. For more information, see our section on [Key-pair authentication for Snowflake connections](/carto-user-manual/connections/snowflake#connecting-to-snowflake-using-key-pair-authentication).

{% endupdate %} {% update date="2025-01-30" tags="new,builder" %} ## Support for aggregating data sources by identical geometries in Builder Are you working with datasets where multiple rows share the same geometry but have varying attributes, such as administrative boundaries, roads, or infrastructure locations? The new [aggregate by geometry](/carto-user-manual/maps/layers#aggregate-by-geometry) functionality allows you to aggregate those features in your layer visualization and interactions, improving performance while keeping access to detailed insights. With this update, you can: * Aggregate geometries in your layer to ensure optimal performance. * Aggregate styling and interaction attributes to retrieve relevant information linked to your aggregated feature. * Maintain widget functionality over the original source, enabling drill-down operations for deeper analysis.

{% endupdate %} {% update date="2025-01-30" tags="new,workflows" %} ## Expand and tailor Workflows functionality with Extension Packages With this new release, users and partners can now extend the capabilities of our low-code analytics tool CARTO Workflows by creating, integrating and distributing custom components tailored to their specific spatial analytics needs. To start creating your own Workflows Extension Packages we have published [this public GitHub template](https://github.com/CartoDB/workflows-extension-template). Kick off your own repository out the template and start developing extensions for BigQuery and Snowflake connections. Additionally, we have published a set of extensions readily available to be installed from the Workflows UI. The initial release boasts a curated collection of extensions, including: * [**BigQuery ML**](/carto-user-manual/workflows/components/bigquery-ml)**:** Integrate machine learning workflows with your geospatial data using BigQuery ML directly within Workflows. * [**Google Earth Engine**](/carto-user-manual/workflows/components/google-earth-engine)**:** Unleash the power of Google Earth Engine for advanced spatial analysis tasks. * [**Google Environment APIs**](/carto-user-manual/workflows/components/google-environment-apis)**:** Bring the power of Google Environment APIs (Solar, Air Quality, Pollen) into your geospatial analytics workflows. * [**Telco Signal Propagation Models**](/carto-user-manual/workflows/components/telco-signal-propagation-models)**:** Analyze telecommunication signals with path profiles, propagation modeling, and obstacle identification. Head over to the CARTO Workflows documentation to learn more about [Extension Packages](/carto-user-manual/workflows/extension-packages) and explore the initial release offerings.

{% endupdate %} {% update date="2025-01-17" tags="new,workspace" %} ## Support for sharing maps with specific users We've introduced the ability to share maps with individual users! Previously, maps could only be shared with the entire organization, specific user groups, or made publicly accessible via a link. With this new feature, Editors now have more granular control over map access permissions. Users can select exactly which individuals should have access to a map (and they can revoke it at any time), making it easier to collaborate on specific projects while maintaining security. For more information, see our section on [publishing and sharing maps](/carto-user-manual/maps/sharing-and-collaboration).

{% endupdate %} {% update date="2025-01-10" tags="new,workspace" %} ## Connect CARTO and Google BigQuery using Workload Identity Federation We’re excited to announce that CARTO now supports connecting to Google BigQuery via **Workload Identity Federation**! This new capability enables secure, seamless authentication without requiring service account keys, making it easier to manage access and improving security for your cloud-native maps, workflows and applications. With Workload Identity Federation, you can set up a trust relationship between CARTO and your Google Cloud projects for a smooth integration — In other words, you will be managing permissions to each of your CARTO users directly in Google Cloud, using IAM rules. Another benefit of this method is that it provides a framework to effortlessly scale and distribute granular permissions across large-scale teams using CARTO and BigQuery. To get started: * Administrators will need to set up an [integration to configure Workload Identity Federation in CARTO](/carto-user-manual/settings/advanced-settings/workload-identity-federation). * Once the integration is set up, all users will be able to [use Workload Identity Federation when connecting CARTO and BigQuery](/carto-user-manual/connections/bigquery#using-workload-identity-federation).

{% endupdate %} {% update date="2025-01-07" tags="improvement,carto-for-developers" %} ## Develop completely custom widgets powered by H3 and Quadbin spatial index-based sources A few months ago we introduced our [framework-agnostic widgets](/whats-new/q4-2024#new-framework-agnostic-widgets-in-carto-for-developers), a new system for developers to add scalable and highly-performant charts and other data components to their CARTO + deck.gl application, with support for vector-based data sources: *points*, *lines* and *polygons*. Today, we're extremely happy to announce that developers can now build completely custom widgets using **spatial index sources** as well. These sources aggregate the data in a spatial index system, such as **H3** or **Quadbin,** for increased performance and scalability. The main benefits of the new framework-agnostic widgets apply to spatial index-based widgets as well: * Build anything using H3 and Quadbin sources: from scorecards to bar charts, tables, time series, and everything in between. * Bring your own UI: Use your favorite charting library or custom HTML components. * Easily sync your widgets with the deck.gl map. * Seamlessly use widgets to filter the map and other widgets, fully leveraging your cloud data warehouse computing power. * Built using JS and Typescript only, they are fully compatible with the framework of your choice (Angular, React, Vue...), adding minimal dependencies. Ready to learn more? Get started by reading the [technical reference](/carto-for-developers/reference/carto-widgets-reference) or by exploring the [examples](/carto-for-developers/examples).

{% endupdate %} {% endupdates %} # Q4 2024 New features and improvements introduced from October to December 2024 {% updates %} {% update date="2024-12-13" tags="improvement,workspace" %} ## Improved SSO group management We've introduced several improvements to help Admins of organizations using SSO groups manage them more effectively. Admins can now view the composition of groups, search for specific users within them, and delete unused groups. Additionally, we've implemented a new method to synchronize only a subset of groups into CARTO. For more details, visit our article on [SSO Groups](/carto-user-manual/settings/users-and-groups/managing-user-groups).

{% endupdate %} {% update date="2024-12-04" tags="improvement,data-observatory" %} ## Discover spatial data like never before: Meet the new Data Observatory Catalog! We’re thrilled to announce a major update to the CARTO Data Observatory catalog! The new version introduces a completely redesigned interface, making it easier than ever to browse and discover spatial datasets. Whether you're searching for demographic insights, mobility or environmental data, the improved catalog helps you navigate a vast array of options with greater clarity and efficiency. In addition to the new design, the updated catalog now includes richer metadata for each dataset. You can access detailed descriptions, links to product documentation, Frequently Asked Questions, and relevant use-cases for each product, enabling more informed decision-making when assessing external datasets to enrich your geospatial analysis. [Log in](https://app.carto.com/) today to explore the new Data Observatory catalog and unlock the full potential of your projects! Access more information about the Data Observatory in our [product documentation](/carto-user-manual/data-observatory).

{% endupdate %} {% update date="2024-11-24" tags="new,carto-for-developers" %} ## Avoid exposing SQL in your CARTO applications with Named Sources There are no trade-offs between simplicity, flexibility and security: developers using CARTO can now use Named Sources to avoid exposing the SQL queries used under the hood in their applications, and without necessarily having to add additional backend or proxy services. Developers can manage their Named Sources manually via UI or programmatically via API. To get started with Named Sources, check the [documentation](/carto-user-manual/developers/named-sources) and the [developer guides](/carto-for-developers/guides/avoid-exposing-sql-queries-with-named-sources).

{% endupdate %} {% update date="2024-11-21" tags="new,deployment-methods" %} ## Fully deploy CARTO within Snowflake using Container Services You can now deploy your own instance of CARTO fully inside of Snowflake, as a Native App using Snowflake-maaged Container Services. From additional security benefits (from a closed environment within Snowflake) to streamlined installation, there are multiple reasons to be excited about this new deployment method, currently in BETA for specific customers. Learn more about [deploying CARTO within Snowflake using Container Services](/carto-native-app-for-snowflake-containers/deploying-carto-using-snowflake-container-services) in our documentation or read about it in our [blog post](https://carto.com/blog/product-announcement-deploy-the-carto-platform-inside-snowflake).

{% endupdate %} {% update date="2024-11-21" tags="new,builder" %} ## Seamless data source switching in Builder maps Builder users can now modify the location or connection of data sources directly in Builder without breaking the map configuration. This ensures that maps retain their overall configuration, as long as the fields in the updated data source have the same name and type. For map components such as style properties, widgets, or interactions that rely on properties not found in the updated data source, the configuration will gracefully fall back to its default settings, ensuring the map remains functional. This functionality allows users to repurpose their maps effortlessly, even when the data source location in their data warehouse changes—eliminating the need to recreate maps from scratch.\ \ [Learn more in our documentation.](/carto-user-manual/maps/data-sources/changing-data-source-location)

{% endupdate %} {% update date="2024-11-11" tags="new,builder" %} ## Reusable custom color palettes in Builder Admin users can now define custom color palettes for their CARTO organization, removing the need to manually add custom color styling in each new Builder map individually. This is a quick and easy way to apply styles consistently across various maps, available to all Editors within an organization. Custom color palettes can be created from the Settings and are applied directly in CARTO Builder. For more information, see our article on [**creating and applying custom color palettes**](/carto-user-manual/settings/customizations/configuring-custom-color-palettes).

{% endupdate %} {% update date="2024-10-31" tags="new,workflows" %} ## Databricks support for CARTO Workflows We are thrilled to announce that CARTO Workflows now supports direct connections to Databricks, significantly enhancing our integration capabilities for the Databricks platform. This new feature empowers Databricks' vast community of data engineers, data scientists, and analysts to seamlessly perform geospatial analysis within CARTO Workflows. This release caps off a series of Databricks-focused updates rolled out over recent months: * We have introduced support for SQL Warehouses and Unity Catalog in [CARTO connections](/carto-user-manual/connections/databricks). * Made Databricks connections available in [Builder and other maps](/carto-user-manual/maps/data-sources/simple-features) across the platform, as well as geospatial applications developed with CARTO. * Enabled [table preparation](/carto-user-manual/maps/performance-considerations#tiles-postgresql) and [tileset creation](/data-and-analysis/analytics-toolbox-for-databricks/reference/legacy/tiler) for high-performance visualizations. Workflows for Databricks leverages [Databricks Spatial SQL](https://carto.com/blog/enhancing-geospatial-analytics-with-carto-databricks), [Apache Sedona](https://sedona.apache.org/latest/) and the[ CARTO Analytics Toolbox](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-databricks) to make geospatial analysis easier and more performant than ever for data scientists, engineers and analysts on Databricks. Being a cloud-native integration, CARTO pushes down all processing to Databricks, profiting from the massive computation capabilities. By embedding these tools directly in Databricks, we are breaking down the geospatial data silo, making geospatial insights more accessible and actionable for enterprise teams.

{% endupdate %} {% update date="2024-10-17" tags="improvement,builder" %} ## Search, highlight and zoom with Builder's Table widget Navigating large geospatial datasets is now faster with our upgraded [Table Widget](/carto-user-manual/maps/widgets/table-widget), featuring **search**, **highlight**, and **zoom** capabilities. You can now easily **search** for specific features within the Table Widget, making them quick to locate. **Hover** over a table row to instantly **highlight** the corresponding feature on the map, and with a click, the map will automatically **zoom** to and center on that feature. We’ve also improved the widget’s configuration, allowing you to label, format, and reorder columns without altering your data source. \\

{% endupdate %} {% update date="2024-10-15" tags="new,builder" %} ## New basemap selector in Builder Many times, a single basemap doesn't fully meet all of your mapping needs. Now, with the new [basemap selector](/carto-user-manual/maps/basemaps/basemap-selector) in Builder, users can easily switch between different basemaps available in your organization. This feature allows you to tailor the visual context of your maps to specific use cases, enhancing the overall data exploration experience.

{% endupdate %} {% update date="2024-10-14" tags="new,builder,carto-for-developers" %} ## Elevate your point visualizations with the new `_carto_point_density` property We’ve added a new styling property, `_carto_point_density`, for point dynamic tiling sources, perfect for visualizing point density. You can use this property in Builder or your custom apps to style your points by radius, fill, or stroke color, making your maps more insightful and visually appealing. Learn more about it in our [documentation](/carto-user-manual/maps/layers/point#using-_carto_point_density-attribute).

{% endupdate %} {% update date="2024-10-09" tags="new,carto-for-developers" %} ## New framework-agnostic widgets in CARTO for Developers Developers using CARTO + deck.gl are scaling and accelerating their geospatial apps with powerful layers, using live data from their cloud data warehouse. **Now, they can also add scalable, interactive charts and widgets to their geospatial applications.** This is what we love about the new [CARTO Widgets](/carto-for-developers/key-concepts/charts-and-widgets): * Use flexible and scalable data models to achieve exactly and quickly what you need: From scorecards to bar charts, tables, time series, and everything in between. * Bring your own UI: Use your favorite charting library or custom HTML components. * Easily sync your widgets with the deck.gl map. * Seamlessly use widgets to filter the map and other widgets, fully leveraging your cloud data warehouse computing power. * Built with JS and Typescript, they are fully compatible with the framework of your choice (Angular, React, Vue...), adding minimal dependencies. **We're excited to see what you build!** — To get started, head over to the [technical documentation](/carto-for-developers/key-concepts/charts-and-widgets) or check the [**new examples for CARTO Widgets**](/carto-for-developers/examples).

{% endupdate %} {% update date="2024-10-07" tags="new,builder" %} ## Dynamic aggregation of point layer into clusters We've introduced a new functionality in Builder to dynamically visualize your point data as **clusters**, helping you gain deeper insights and uncover trends more effectively. By aggregating point data into clustering, you can: * **Reduce Visual Clutter**: Automatically group nearby points into clusters as you zoom out, helping you maintain clarity and readability, even with dense datasets. * **Enhanced Performance**: Clustering improves performance by reducing the number of individual features rendered, making it easier to handle large datasets without compromising speed. * **Meaningful Aggregation**: See patterns emerge as points are grouped into clusters, helping you identify hotspots, trends, and areas of interest quickly and effectively. * **Interactive Exploration**: As you zoom in and out, clusters dynamically adjust, revealing individual points as you get closer, giving you seamless interaction with your data at different scales.

{% endupdate %} {% endupdates %} # Q3 2024 New features and improvements introduced from July to September 2024 {% updates %} {% update date="2024-10-04" tags="new,workspace" %} ## Enforcing SSO for all users within an organization We've introduced a new toggle in the settings that allows Admins to enforce SSO within their organization. When enabled, every single user in that organization will have to authenticate using Single Sign-On, regaldless of their role. Users that try to authenticate with other mechanisms, such as *User/Password* and *Google Account* will not be allowed to log in. For more details, check out our section on [SSO](/carto-user-manual/settings/sso).

{% endupdate %} {% update date="2024-09-26" tags="new,workflows" %} ## New Export Feature and Enhanced Security for Workflows We’re pleased to introduce several updates to **Workflows** designed to improve both functionality and security: **Export Data from Any Node** A new [**Export**](https://docs.carto.com/carto-user-manual/workflows/results-panel#export-nodes-data) button is now available on the Data tab for every executed node in your workflow canvas, allowing you to export data directly. This asynchronous export process can be tracked via the Activity Panel, similar to how [exports are managed in **Builder**](/carto-user-manual/maps/exporting-data#exporting-data-as-an-editor). **Enhanced Security for Enterprise-Ready Components** In line with our ongoing platform-wide security initiative, we've implemented the following updates: * [**Send by Email**](/carto-user-manual/workflows/components/input-output#save-as-table) now works without requiring attached data, offering more flexibility in workflow automation. * You can now specify a **custom bucket location** when using the **Send by Email** component, giving you control over where your data is sent. * [**Export to Bucket**](/carto-user-manual/workflows/components/input-output#export-to-bucket) no longer uses public buckets. Users are now required to specify their own **bucket locations**, ensuring more secure data management. These updates make **Workflows** an even more powerful tool for enterprise users while maintaining a focus on security and ease of use.

{% endupdate %} {% update date="2024-09-11" tags="new,workspace" %} ## Require Viewer Credentials for Snowflake OAuth connections Users can now require viewer credentials for their Snowflake OAuth connections. When this option is enabled, anyone accessing data through the connection — whether they're consuming maps, running workflows, or using the data explorer — will need to authenticate with their own credentials. This ensures that security policies set in the database, such as Row-Level Security, are enforced. For more details, visit our section on [Sharing connections](/carto-user-manual/connections/sharing-a-connection).

{% endupdate %} {% update date="2024-08-30" tags="new,workspace" %} ## Monitor what's happening in your CARTO organization with the new Activity Data As organizations roll out CARTO to different teams and larger groups of users, it becomes increasingly important **for administrators to understand and monitor how their organization is using CARTO,** and this is now easy, powerful and flexible thanks to the **new** [**CARTO Activity Data**](/carto-user-manual/settings/activity-data) **feature** Administrator can now easily export (manually or programmatically via API) a comprehensive data collection of everything that happened within their CARTO organization. The new Activity Data can be then analyzed to deeply understand things like: * Basic engagement indicators: *weekly active users, workflows run per week*... * Most used features: *most used workflow components...* * Quota consumption: *who is consuming more quota and why* * And many more insights about your CARTO organization Want to get started? Head over to the [CARTO Activity Data](/carto-user-manual/settings/activity-data) documentation. Make sure to also check the full [Activity Data Reference](/carto-user-manual/settings/activity-data/activity-data-reference), as well as the [Examples](/carto-user-manual/settings/activity-data/activity-data-examples) where we share practical guides and SQL queries on how to analyze this data.

{% endupdate %} {% update date="2024-07-31" tags="improvement,workspace" %} ## Improved asset ownership transfer We've introduced an improved flow for transferring user assets (maps, workflows, connections, etc) when deleting a user or when downgrading an Editor/Admin to Viewer. From now on, Admins will be able to select the specific user that will receive the assets. For more information, check our documentation on [Deleting users](/carto-user-manual/settings/users-and-groups/deleting-users) and [Managing user roles](/carto-user-manual/settings/users-and-groups/managing-user-roles).

Selecting the user that will inherit the assets of a deleted user

{% endupdate %} {% update date="2024-07-31" tags="new,builder" %} ## Dynamic aggregation of point layer into H3 cells We've introduced a new functionality in Builder to dynamically visualize your point data as H3 aggregations, helping you gain deeper insights and uncover trends more effectively. By aggregating point data, you can: * **Simplify Complex Data**: Aggregate large volumes of point data into meaningful patterns and trends, making it easier to interpret and analyze. * **Enhance Performance**: Improve rendering times and performance, especially with large datasets, by reducing the number of individual points displayed. * **Identify Hotspots**: Quickly identify areas of high density or activity, helping you make data-driven decisions. * **Visual Clarity**: Reduce visual clutter by grouping nearby points, providing a clearer and more informative map visualization. Simply select this new visualization type and enjoy the benefits of aggregated data visualization, all with exceptional performance thanks to CARTO's native support for spatial indexes.

{% endupdate %} {% update date="2024-07-29" tags="new,builder" %} ## Enhanced layer panel and spatial source definition in Builder We are excited to introduce an improved layer panel in Builder for configuring your layers. This update significantly enhances the UI and UX of this panel, making the experience of creating visualizations in Builder even more enjoyable and efficient. The redesigned panel features a cleaner layout and includes a new 'Data' section at the top. In this new section, you can define the spatial definition of the source linked to your layer. This is especially useful if your source contains multiple spatial columns or if Builder cannot recognize the spatial column by default. Learn more about the spatial definition of your sources [here](/carto-user-manual/maps/data-sources/defining-source-spatial-data). Also, explore our [updated documentation section](/carto-user-manual/maps/layers) for layers to get the most out of this update.

{% endupdate %} {% update date="2024-07-29" tags="new,workflows" %} ## Workflows Templates now available directly from Workspace We are pleased to announce the integration of our [collection of Workflow templates](https://academy.carto.com/creating-workflows/workflow-templates) directly within the CARTO Workspace. This feature aims to streamline your workflow creation process, making it faster and more efficient to [access and utilize pre-built templates](/carto-user-manual/workflows#workflow-templates). * **Integrated Collection**: Access a wide range of workflow templates hosted on the CARTO Academy website, now readily available in the CARTO Workspace. * **Simplified Process**: Users no longer need to visit the Academy site to download and import templates. The new feature allows you to easily recreate templates by selecting ‘New Workflow > From template’ within the Workspace. * **Enhanced Usability**: This integration ensures that all available templates can be accessed with just a few clicks, promoting best practices and facilitating quicker setup of workflows. This feature is designed to ease the learning curve by providing immediate access to valuable workflow templates that illustrate both building blocks for common geospatial analytics and more complex use cases, like industry-specific analysis for Telco, Insurance, Retail and CPG, Out of Home advertising, etc

{% endupdate %} {% update date="2024-07-19" tags="new,builder" %} ## Zoom to layer extent in Builder maps We are excited to introduce the zoom to layer functionality in Builder, which allows you to easily zoom to the layer extent, providing an immediate view of your dataset. When layers are filtered by widgets or parameters, the zoom focuses on the filtered data, ensuring you see exactly what's relevant. Additionally, we have incorporated a "Show only this/Show all layers" feature, allowing you to quickly toggle all layers on and off with a single action, especially useful for maps including multiple layers. Whether you're exploring vast datasets or gathering insights on geospatially distributed features, these new features will ensure a better exploration experience! Learn more about this feature in our [documentation](/carto-user-manual/maps/layers/zoom-to-layer).

{% endupdate %} {% update date="2024-07-15" tags="new,workflows" %} ## New Workflows Components for Creating Tilesets We are excited to introduce a powerful new set of components in Workflows that significantly enhance your geospatial data processing capabilities. These components are designed to facilitate the creation of various types of tilesets, allowing for efficient visualization and analysis of large spatial datasets. Here are the key features: **Create Vector Tileset** Generate vector tilesets from point, line, or polygon tables, enabling smooth and interactive map experiences. **Create Point Aggregation Tileset** Aggregate point data along with their properties into tilesets, ideal for visualizing dense point data on maps. **Create Quadbin Aggregation Tileset** Generate tilesets by aggregating quadbin indices, providing a fast and scalable way to manage spatial hierarchies and visualize large datasets. **Create H3 Aggregation Tileset** Utilize H3 hexagonal indexing to create aggregated tilesets, perfect for detailed spatial analysis and representation. These new components enable you to transform your spatial data into highly efficient and scalable tilesets, which can be seamlessly integrated into your mapping applications. For more detailed information on how to use these components, visit [our documentation](https://docs.carto.com/carto-user-manual/workflows/components/tileset-creation).

{% endupdate %} {% endupdates %} # Q2 2024 New features and improvements introduced from April to June 2024 {% updates %} {% update date="2024-06-28" tags="new,workspace" %} ## Support for organizing and filtering maps and workflows with tags We are happy to announce a new system to allow users to classify and filter maps and workflows in the CARTO Workspace with tags. With this new feature, editor users will be able to create, apply and filter maps and workflows by tags, considerably improving the organization of assets within CARTO. With this new enhacement: * You can create, apply and remove tags by editing the Map/Workflow properties from the Workspace. * We have added a tag filter to the Workspace so you can filter by one or several tags. * Once a tag filter is applied, you can copy the URL for sharing that Workspace view internally. * Tags will be automatically removed when they are no longer applied to any map or workflow.

Creating and applying a tag in the Maps Workspace

{% endupdate %} {% update date="2024-06-28" tags="new,analytics-toolbox" %} ## Network planning and coverage analysis for Telco with the Analytics Toolbox for BigQuery We are thrilled to announce our new functions for line of sight and signal propagation analysis in the Analytics Toolbox for BigQuery. These new procedures, available in the [telco](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/telco) module, enable network planners to run **coverage analysis** natively within BigQuery. With this functions users can now assess the geographical areas where current or potential new network's signal is available and evaluate its quality. This release includes procedures for: * **Path profile** analysis to evaluate the **line of sight** and identify potential obstructions between two points; * **Path loss** estimation of a signal as it propagates through an environment, with options for the [Close In](https://arxiv.org/pdf/1602.07533) and [Extended Hata models](https://www.itu.int/dms_pub/itu-r/opb/rep/R-REP-SM.2028-2-2017-PDF-E.pdf). Learn more about these new features in our [documentation](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/telco), and start testing them by following our step-by-step [tutorial](https://academy.carto.com/advanced-spatial-analytics/spatial-analytics-for-bigquery/step-by-step-tutorials/analyzing-signal-coverage-with-line-of-sight-calculation-and-path-loss-estimation).

{% endupdate %} {% update date="2024-06-28" tags="new,analytics-toolbox" %} ## New space-time analysis capabilities in the Analytics Toolbox for BigQuery We are excited to announce the addition of two new space-time analyses available in the [statistics](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/statistics) module of the Analytics Toolbox for BigQuery: * [**Space-time hotspot classification**](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/statistics#spacetime_hotspots_classification)**,** to classify hotspots based on changes in their intensity over time, such as strengthening hotspots, declining hotspots, occasional hotspots, and more; * [**Time-series clustering**](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/statistics#time_series_clustering)**,** to identify locations with similar temporal behaviors. Learn more on how to perform these spatiotemporal analyses by exploring our tutorials for [space-time hotspot classification](https://academy.carto.com/advanced-spatial-analytics/spatial-analytics-for-bigquery/step-by-step-tutorials/spacetime-hotspot-classification-understanding-collision-patterns) and [time-series clustering](https://academy.carto.com/advanced-spatial-analytics/spatial-analytics-for-bigquery/step-by-step-tutorials/time-series-clustering-identifying-areas-with-similar-traffic-accident-patterns).

{% endupdate %} {% update date="2024-06-20" tags="new,builder,carto-for-developers" %} ## Heatmap visualizations at scale for massive point-based data We are thrilled to announce density heatmap visualization for vast point datasets! This new feature allows you to render large point datasets as a heatmap in a scalable and performant manner. Available now in **Builder**, you can easily identify hotspot patterns and gain insights from your data. Developers can also build their own large-scale heatmaps in their apps using **CARTO + deck.gl**, with the new `heatmapTileLayer` (Experimental). Learn more from our [documentation](https://deck.gl/docs/api-reference/carto/heatmap-tile-layer) and [examples](https://github.com/CartoDB/deck.gl-examples/tree/master/dynamic-tiling-heatmap).

{% endupdate %} {% update date="2024-06-19" tags="new,workflows" %} ## Improved Data Importing Capabilities in Workflows We are excited to introduce enhanced data importing capabilities in CARTO Workflows. This new release includes a variety of features designed to simplify and expand the ways you can import data into your workflows, providing greater flexibility and functionality. **New Features:** **Import from URL Component** * This [**new component**](/carto-user-manual/workflows/components/input-output#import-from-url) allows users to import data directly from a public URL. It is compatible with BigQuery, Snowflake, Redshift, and PostgreSQL. By leveraging the CARTO Import API, this component ensures seamless data integration across different database systems. * The [**Import from URL** ](/carto-user-manual/workflows/components/input-output#import-from-url)component supports workflows that run on a schedule or are executed via API, providing more robust and automated data management options. **Sunset of Previous Method** * The [previous data importing method](/carto-user-manual/workflows/workflow-canvas#import-a-file-to-your-workflow), which was limited to UI-based operations, will be deprecated. The new Import from URL component provides a more versatile and powerful alternative. **Quick Import from your desktop** * Users can now quickly [**import files**](/carto-user-manual/workflows/data-sources#files) from their computers directly into the workflow canvas. This feature supports drag-and-drop functionality, making it easier to integrate local files into your workflows. * Files uploaded in this manner remain accessible within each workflow, ensuring consistent data availability and management.

{% endupdate %} {% update date="2024-06-03" tags="new,builder" %} ## Support for calling external API services from Workflows We are thrilled to announce a powerful new feature for Workflows: the ability to connect your workflows with external API services. With this new capability, we enabling use cases like the following: * Retrieve Data from External APIs: Augment your datasets by pulling in information from APIs such as Google Environment APIs, government, cadaster, parcel data, and other specialized data sources. * Trigger Actions via API: Automatically trigger external processes, send notifications, or execute commands directly from your workflows, like: * Notify on chat applications: Send real-time notifications to your company's channels to keep your team updated on workflow executions. * Integrations with automation tools: Integrate with automation tools to trigger external actions from a Workflow execution. * Send data from your Workflows to external APIs: Use data from any node in your workflow to build the body for a request. Leverage all this new functionality by using the new [**HTTP Request**](https://docs.carto.com/carto-user-manual/workflows/components/input-output#http-request) component: A dedicated Workflows component that facilitates making requests to external APIs, providing enhanced versatility and extensibility. It uses the `http_request` module from the CARTO Analytics Toolbox.\ \ It also supports [custom expressions and variables](/carto-user-manual/workflows/using-variables-in-workflows#using-variables-and-expressions-in-components) to embed logic directly into component settings using SQL operators combined with variable and column values.\\

{% endupdate %} {% update date="2024-05-16" tags="new,builder" %} ## Support for custom basemaps in Builder A basemap is a crucial component of any map, providing essential context, spatial features, and the visual foundation for your creations. To meet the unique needs of each organization, we now enable you to bring your own basemap directly into your CARTO organization. Admin users at CARTO can now upload custom basemaps and tailor the basemap gallery options available to Editor users in Builder. Unleash your creativity and enjoy an enhanced map-making experience while maintaining a cohesive and consistent selection of basemaps throughout your organization.\ \ To learn more about how you can upload custom basemaps to the CARTO platform and the supported formats, check [this page](/carto-user-manual/settings/customizations/configuring-your-organization-basemaps). For a step-by-step guide on custom basemaps, check out our [new tutorial](https://academy.carto.com/building-interactive-maps/data-visualization/customize-your-visualization-with-tailored-made-basemaps) in the Academy.

{% endupdate %} {% update date="2024-05-14" tags="improvement,builder" %} ## Performance optimizations in Builder maps We are excited to introduce a set of enhancements in CARTO Builder designed to further improve the performance of our interactive map visualizations. With these improvements, Builder will: * **Load only essential properties**: Builder will now load only the essential properties from your tables or SQL queries when they are needed in the map. This reduces unnecessary data transfer and speeds up processing. * **Reduce tile requests**: The number of tile requests has been significantly reduced, resulting in faster map loading times and a smoother user experience. * **Limit simultaneous queries**: To enhance stability and prevent overload, Builder will limit the number of simultaneous queries, ensuring a more reliable performance. These enhancements are part of our ongoing commitment to providing the best possible experience with CARTO Builder.

{% endupdate %} {% update date="2024-04-29" tags="improvement,workspace" %} ## Redesigning our Developers section in CARTO Workspace We believe that all paths to success start from the CARTO Workspace, and the path to successfully developing powerful geospatial apps isn't an exception. With this in mind, we've carefully redesigned the experience when accessing the Developers section, and these are the highlights: * New Overview with a curated list of [documentation, guides and examples](https://github.com/CartoDB/gitbook-documentation/blob/master/whats-new/broken-reference/README.md). * A simplified [Credentials](/carto-user-manual/developers/managing-credentials) system to manage all your authentication methods. * This change unifies the management of API Access Tokens and OAuth Clients (*previously known as Applications*) in a single section, making more clear what each method is best for. * A new list containing all your [API-enabled Workflows](/carto-user-manual/workflows/executing-workflows-via-api), for easy access. Additionally, we've simplified the way that organizations decide the content in their [Applications](/carto-user-manual/applications) section. Before, it was a mix of developer credentials and apps registered by the administrator. Now, administrators in CARTO are in full control of [managing Applications](/carto-user-manual/settings/advanced-settings/managing-registered-apps), including the visibility/sharing settings. *Developer credentials created before April 25th have been duplicated as applications to maintain the same visibility level as previously.* [*Read more here.*](/carto-user-manual/developers/managing-credentials)

{% endupdate %} {% update date="2024-04-24" tags="new,workspace,workflows" %} ## Extended support for raster data sources in Data Explorer and Workflows We're happy to introduce a suite of powerful new features that are set to enable working with raster data in CARTO. Before these were available, working with raster data required using external CLI applications and dealing with SQL queries manually in order to leverage the analytical capabilities of the CARTO Analytics Toolbox for Snowflake and BigQuery. **Import Cloud Optimized GeoTIFFs**: Say goodbye to cumbersome raster data ingestion processes. With our latest enhancements, you can now effortlessly import Cloud Optimized GeoTIFFs to [Snowflake](/data-and-analysis/analytics-toolbox-for-snowflake/guides/working-with-raster-data) and [BigQuery](/data-and-analysis/analytics-toolbox-for-bigquery/guides/working-with-raster-data) via both the Import API and the [Workspace UI](/carto-user-manual/data-explorer/importing-data). This provides a streamlined and efficient method for ingesting raster files into BigQuery and Snowflake, ensuring optimal storage efficiency and fast query access. **Raster Tables in Data Explorer**: Dive deeper into your raster data in the data warehouse with full support for raster tables in the Data Explorer. Gain access to a specific set of metadata and custom actions for raster tables. **Workflow Components for Raster Analysis**: Take your spatial analyses to the next level with our new Workflow components designed specifically for working with raster data sources. Whether you're looking to extract raster values or perform complex intersect and aggregate operations, our new components, including "[Get Raster Values](/carto-user-manual/workflows/components/raster-operations#get-values-from-raster)" and "[Intersect and Aggregate Raster](/carto-user-manual/workflows/components/raster-operations#intersect-and-aggregate-raster)", provide you with the tools you need to unlock valuable insights from your raster datasets.

{% endupdate %} {% update date="2024-04-17" tags="new,builder" %} ## Generate PDF reports from your Builder maps We’ve launched a new feature that allows you to download detailed PDF reports of your interactive Builder maps. These reports capture everything from the current map extent to widgets, parameters, and the map description. Whether you're sharing insights with colleagues, presenting to stakeholders, or documenting your analysis, this new feature packs the richness of your interactive maps into a portable, easy-to-share format.

{% endupdate %} {% update date="2024-04-11" tags="improvement,workspace" %} ## Get quicker, better answers with the new AI-powered help sidebar A new **AI-powered help assistant** can now be found in the Help sidebar, available at all times from CARTO Workspace, Builder and Workflows. It will provide quick answers based on our documentation and will link to the most relevant resource. With our documentation evolving and growing in size and depth, this AI-powered tool will save precious time and will guide you in the right direction without leaving CARTO. Ask anything!

{% endupdate %} {% endupdates %} # Q1 2024 New features and improvements introduced from January to March 2024 {% updates %} {% update date="2024-03-31" tags="new,builder" %} ## Preview Builder maps during edition This new feature simplifies the map-making process by letting Editor users switch seamlessly between editing and previewing. With [Preview mode](/carto-user-manual/maps/sharing-and-collaboration/map-preview-for-editors), these users can easily see how the map will look like to viewers, allowing them to review and refine it before sharing. This smooth workflow ensures that maps are well-presented and meet the highest standards of clarity and effectiveness. Additionally we've enhanced our map-sharing functionality to deliver a smoother and more intuitive experience. This update focuses on streamlining the process of sharing maps with others, ensuring a more seamless interaction. Dive into the details of these improvements in our [documentation](/carto-user-manual/maps/sharing-and-collaboration).

{% endupdate %} {% update date="2024-03-27" tags="new,carto-for-developers" %} ## Introducing: deck.gl v9 A **new major version of deck.gl** is out. deck.gl is the open-source visualization library that powers all CARTO visualizations, and one of the main components of [CARTO for Developers](https://github.com/CartoDB/gitbook-documentation/blob/master/whats-new/broken-reference/README.md). * For a complete changelog, visit the official [**deck.gl what's new**](https://deck.gl/docs/whats-new). * To address breaking changes, read the official [**deck.gl upgrade guide**](https://deck.gl/docs/upgrade-guide). Changes in the CARTO module are also addressed there. * We have also published a complete set of [**new examples using CARTO + deck.gl**](/carto-for-developers/examples). We're very happy to see CARTO joining efforts with many other contributors from the vis.gl and OpenJS Foundation communities. Read more about this release in the [CARTO blog](https://carto.com/blog/announcing-deck-gl-v9-webgpu-ready-with-typescript-support).

{% endupdate %} {% update date="2024-03-21" tags="new,workflows" %} ## Support for scheduling the execution of workflows With this new capability, analytical pipelines created with Workflows can be [**scheduled**](/carto-user-manual/workflows/scheduling-workflows) so they are executed on a specific period: * **Hours:** The workflow will be executed every X hours, at o'clock times. * **Days:** The workflow will be executed every day at a specific time. * **Weeks:** The workflow will be executed weekly, on a specific day, at a specific time. * **Months:** The workflow will be executed monthly, on a specific day, at a specific time. * **Custom:** Use a custom expression to define the schedule. CARTO leverages native scheduling capabilities on each data warehouse to provide this functionality in all CARTO Data Warehouse, BigQuery, Snowflake and PostgreSQL connections.

{% endupdate %} {% update date="2024-03-14" tags="improvement,builder" %} ## Support for private embedding of CARTO Builder maps Maps created with CARTO Builder can now be embedded anywhere — **even when they're not shared publicly**. With private embedding you can restrict and maintain control over who can view these maps when embedded on web pages or apps. To leverage private embedding simply share your map with the organization or with the specific groups you want to share the map with. These users need to be previously logged-in to CARTO to view the embedded map. Learn more at our [Embedding maps documentation](/carto-user-manual/maps/sharing-and-collaboration/embedding-maps).

An example of a private embedded map where the user does not have access to the embedded content

{% endupdate %} {% update date="2024-02-29" tags="new,workflows" %} ## New Workflows components for low-code geospatial analytics During the last few weeks, we’ve been progressively adding new and improved components in CARTO Workflows: * [**Case When**](https://docs.carto.com/carto-user-manual/workflows/components/data-preparation#case-when) component for supporting column values based on conditional expressions. * [**Edit Schema**](https://docs.carto.com/carto-user-manual/workflows/components/data-preparation#edit-schema) component (replacing Refactor Columns): clean schemas, rename and cast columns. * Added ‘Append’ mode to [**Save as Table**](https://docs.carto.com/carto-user-manual/workflows/components/import-export#save_as_table)**.** * Added ‘Maximum distance’ setting to [**K-Nearest Neighbors**](https://docs.carto.com/carto-user-manual/workflows/components/spatial-analysis#knn_neighbors). * Added [**Extract from JSON**](https://docs.carto.com/carto-user-manual/workflows/components/data-preparation#extract-from-json) for extracting values from JSON columns using the native syntax from each data warehouse. * Added ‘Mode’ setting to [**H3 Polyfill**](https://docs.carto.com/carto-user-manual/workflows/components/spatial-indexes#h3_polyfill) and [**Quadbin Polyfill** ](https://docs.carto.com/carto-user-manual/workflows/components/spatial-indexes#quadbin_polyfill)components. * [**Subdivide**](https://docs.carto.com/carto-user-manual/workflows/components/spatial-operations#subdivide) to split larger geometries into easier-to-process smaller features. * New UI for [**Draw Custom Features**](https://docs.carto.com/carto-user-manual/workflows/components/parsers#draw-custom-features) component * [**Composite Score Supervised**](https://docs.carto.com/carto-user-manual/workflows/components/statistics#composite-score-supervised): Create composite scores with the supervised method using this component. [Take a look at the example template](https://academy.carto.com/creating-workflows/workflow-templates/statistics#create-a-composite-score-with-the-supervised-method-bigquery). * [**Composite Score Unsupervised**](https://docs.carto.com/carto-user-manual/workflows/components/statistics#composite-score-unsupervised)**:** Create composite scores with the supervised method using this component. [Take a look at the example ](https://academy.carto.com/creating-workflows/workflow-templates/statistics#create-a-composite-score-with-the-unsupervised-method-bigquery)template

{% endupdate %} {% update date="2024-02-21" tags="improvement,builder" %} ## Extended support for URL parameters in Builder maps Exciting news – CARTO Builder has expanded its [URL parameter](/carto-user-manual/maps/sharing-and-collaboration/url-parameters) capabilities to include widgets, SQL parameters, search locations, and feature selections. Now, when viewers interact with these elements, the URL updates in real time, making it easier to share customized map views. This update opens up possibilities for creating varied views from a single map, simplifying sharing, and minimizing the need for multiple map versions. It also enhances the embedding of maps into websites or apps, providing a seamless user experience without unnecessary redirections.

{% endupdate %} {% update date="2024-02-19" tags="improvement,workspace" %} ## Distinguish Users by authentication method We have added a new column to the *Users and Groups* table of the Organization Settings which displays the authentication method used by each user (Google Account, Username/Password, SSO or Github). This will help Admins better manage their organization, avoid confusion and identify users quickly.

{% endupdate %} {% update date="2024-02-08" tags="new,workflows" %} ## Support for configuring and executing your workflows with an API call We are excited to announce the release of a comprehensive set of new features in CARTO Workflows designed to provide the **ability to trigger the execution of your workflows by calling an API**. * **Variable definition**: [Define variables](/carto-user-manual/workflows/using-variables-in-workflows#creating-variables) that can be used within components' settings. These variables can also be configured as parameters, allowing for inputing dynamic values during API calls. * **Expression support**: Introducing expressions! [Embed logic](/carto-user-manual/workflows/using-variables-in-workflows#using-variables-in-components) directly into component settings, enabling the use of SQL operators in conjunction with variable and column values from your data. * **API endpoint for triggering workflows**: [Enable an API endpoint](/carto-user-manual/workflows/executing-workflows-via-api#enabling-api-access-for-a-workflow) to initiate a workflow execution. This endpoint exposes all parameters set as variables, facilitating smooth integration. * **Workflow status polling**: [Easily monitor](/carto-user-manual/workflows/executing-workflows-via-api#checking-status-of-a-workflow-execution) the status of workflow execution. * **Output definition and storage**: [Define the output of a workflow API execution](/carto-user-manual/workflows/executing-workflows-via-api#output-of-a-workflow-executed-via-api), which will be stored in a temporary table. The Fully Qualified Name (FQN) of this table is included in the API response for effortless access post-execution. This output can be used along with other options like exporting result to a bucket, saving to a static table or send an email with the result. * **Controlled caching behavior**: Have control over caching behavior across all execution modes: UI, [Scheduled (Beta)](/carto-user-manual/workflows/scheduling-workflows), and via [API](/carto-user-manual/workflows/executing-workflows-via-api#running-a-workflow-via-api-call). All these elements have been built to enable users to **integrate workflows** into larger analytical processes, and to embed **asynchronous analytical** capabilities into web applications.

{% endupdate %} {% update date="2024-01-15" tags="improvement,workspace" %} ## Improvements when sharing map and workflow links to new users We have released a set of improvements that affect the **experience of new users when they open a** [**shared map**](/carto-user-manual/maps/sharing-and-collaboration) **or** [**shared workflow**](/carto-user-manual/workflows/sharing-workflows) **for the first time**. Previously, you had to invite those users or have them sign up manually. Now: * If your organization uses [Single Sign-On (SSO)](/carto-user-manual/settings/sso), all maps and workflows shared links will redirect to your SSO login page for easier adoption and onboarding of new users * The unauthenticated screen for all shared maps and workflows has been redesigned for clarity * Users can now login or signup through the map/workflow link, and they will be **automatically redirected to the desired map/workflow once successfully authenticated**

{% endupdate %} {% update date="2024-01-11" tags="new,documentation" %} ## New CARTO Academy - tutorials, videos and templates to boost your spatial analysis skills We are happy to announce the launch of our new [CARTO Academy](https://academy.carto.com), with detailed tutorials, videos and templates to boost your spatial analysis skills and make you a proficient user of the CARTO platform. Among others, in this new CARTO Academy you will find materials to get you started with [Spatial Indexes](https://academy.carto.com/working-with-geospatial-data/introduction-to-spatial-indexes), tutorials to help you build stunning [visualizations](https://academy.carto.com/building-interactive-maps/data-visualization) and [spatial analyses](https://academy.carto.com/building-interactive-maps/data-analysis) with CARTO Builder, step-by-step [tutorials](https://academy.carto.com/creating-workflows/step-by-step-tutorials) and [templates](https://academy.carto.com/creating-workflows/workflow-templates) for Workflows, and guides to develop your advanced spatial analysis skills with [Google BigQuery](https://academy.carto.com/advanced-spatial-analytics/spatial-analytics-for-bigquery/step-by-step-tutorials), [Snowflake](https://academy.carto.com/advanced-spatial-analytics/spatial-analytics-for-snowflake/step-by-step-tutorials) and [AWS Redshift](https://academy.carto.com/advanced-spatial-analytics/spatial-analytics-for-redshift/step-by-step-tutorials).

{% endupdate %} {% endupdates %} # Older entries Archived release notes from 2022 and 2023 {% hint style="info" %} These are archived What's New entries from 2022 and 2023. For the latest updates, see [What's new](/whats-new). {% endhint %} {% updates %} {% update date="2023-12-20" tags="improvement,builder" %} ## Enhancements to export data from Builder maps We've upgraded the [export functionality](/carto-user-manual/maps/exporting-data) in Builder maps, shifting the data export process to work in server-side mode for an enhanced efficiency and data integrity. This improvement ensures a more reliable data retrieval experience. Additionally, when exporting data as CSV, it now includes the geometry column in WKT (Well-Known Text) format, if applicable. This enhancement simplifies data handling and boosts compatibility with various geospatial tools, making integrations smoother. Looking to leverage this enhanced functionality for RDS for PostgreSQL data sources? Don't forget to set up the necessary S3 bucket integration to enable the export feature. For more details and guidance, check out our [documentation](/carto-user-manual/settings/advanced-settings/configuring-s3-bucket-integration-for-rds-for-postgresql-exports-in-builder).

\\ {% endupdate %} {% update date="2023-12-18" tags="new,workflows" %} ## ML Generate Text component available for Workflows We have added a [new component](/carto-user-manual/workflows/components/generative-ai#ml-generate-text) to Workflows that leverages [BigQuery ML Generate Text](https://cloud.google.com/bigquery/docs/reference/standard-sql/bigqueryml-syntax-generate-text) capabilities to allow embedding Generative AI functionalities into your geospatial analytical pipelines. It can be used to help analyze the result of an enrichment; to generate labels or categories based on variables on your table; or could also generate new content for each row on your data, using different variables to compose a prompt that will be evaluated on each row. With this new addition, Generative AI capabilities are handy and readily available from Workflows.

{% endupdate %} {% update date="2023-11-28" tags="new,workflows" %} ## Export Workflows results to a bucket We have just released a [new component in Workflows](/carto-user-manual/workflows/components/input-output#export-to-bucket) that allows exporting the result from any node in a workflow to a storage bucket. The node's data will be exported as a series of files, which URLs will be stored in a table. Just inspect the Data tab in the results panel to access the links to each file. This component is currently available for all CARTO Data Warehouse and BigQuery connections.

{% endupdate %} {% update date="2023-11-27" tags="improvement,workflows" %} ## Improvements to the results panel in Workflows We have added a few improvements to the results panel in Workflows that are focused on better usability and data exploration capabilities: * Renovated, sleeker design; * See when the workflow was executed for the last time; * Easily find the number of columns and rows of a result; * Explore the complete result with pagination for optimal performance; * Copy the content of a page to the clipboard, ready to be pasted into a spreadsheet; * Analyze statistics of each column: * Frequency of the Top 20 categories for string, date and timestamp columns; * Maximum and minimum values, average and sum for numeric columns. * SQL control code is hidden to facilitate readability. Find all the documentation about these improvements [here](/carto-user-manual/workflows/results-panel). {% embed url="" %} {% endupdate %} {% update date="2023-11-22" tags="new,workspace" %} ## Support for OAuth connections in Snowflake You can now set up an OAuth integration to connect CARTO and Snowflake. This allows users to follow their usual Snowflake login flow (**Snowflake OAuth**) to set up their connections in CARTO, which has security benefits and is a more familiar process for all Snowflake users. If you have an external identity provider integrated in Snowflake such as Azure Active Directory or Okta, we also support **External OAuth** to achieve the same process. Read more about [Configuring OAuth connections to Snowflake](/carto-user-manual/connections/snowflake#connecting-to-snowflake-via-oauth).

{% endupdate %} {% update date="2023-11-16" tags="new,builder" %} ## Measure point-to-point distances in Builder maps We're excited to announce the latest feature in Builder - a [distance measure](/carto-user-manual/maps/measure-distances) tool that will allow users to measure distances between two points on their maps. This new functionality is ideal for a diverse range of use cases, from planning tasks to gaining a deeper understanding of spatial relationships between various map elements.

{% endupdate %} {% update date="2023-11-06" tags="new,builder" %} ## Style qualitative data using hex color codes In Builder, you now have the capability to style your qualitative data using hex color codes pulled directly from your table or SQL query sources. If you're curious about generating these hex color codes, we've prepared a [tutorial](https://academy.carto.com/building-interactive-maps/data-visualization/style-qualitative-data-using-hex-color-codes) to assist you, detailing the steps using either Workflows or SQL. What's especially exciting? The range of possibilities this opens up. Whether you're aligning with your company's branding, looking to automatically style a high number of categories, or exploring diverse color schemes, the choice is all yours.

{% endupdate %} {% update date="2023-10-25" tags="new,workflows" %} ## Collection of Workflows examples We have just published a new collection of workflows examples, designed with a hands-on approach to empower users and ease the learning curve for using CARTO Workflows. It showcases a wide range of scenarios, from simple building blocks for your geospatial analysis to more complex, industry-specific workflows tailored to suit specific use cases. Take a look at our catalog of workflows examples [**here**](https://academy.carto.com/creating-workflows/workflow-templates)! {% embed url="" %} {% endupdate %} {% update date="2023-10-25" tags="new,workflows" %} ## Improved import capabilities in Workflows We have added a new mechanism to [**import a workflow into your account**](/carto-user-manual/workflows/sharing-workflows#import-a-workflow-from-a-sql-file). Just download an example from the gallery, drag and drop into your CARTO Workspace (or browse a file from your computer) and the workflow will be automatically re-created in your account. And also we have just added a new way to [**import data into a workflow**](/carto-user-manual/workflows/workflow-canvas#import-a-file-to-your-workflow). Either from a local file in your computer, or from a URL, this new feature facilitates the task of incorporating data into your analytical pipelines. {% embed url="" %} {% endupdate %} {% update date="2023-10-18" tags="new,builder" %} ## New Pie Widget available in Builder The new [Pie Widget](/carto-user-manual/maps/widgets/pie-widget) is designed to simplify the visualization of complex categorical data in Builder, making it more user-friendly and insightful. Thanks to this new feature you can quickly and easily analyze data proportions and category weights, allowing for better understanding of each data category within your dataset. This enhancement empowers users to make more informed decisions by providing a clearer view of their data.

{% endupdate %} {% update date="2023-09-30" tags="improvement,builder" %} ## Multiple series and custom temporal aggregations in the Time Series Widget We have upgraded our Time Series Widget in Builder to boost your temporal data analysis experience. These enhancements bring a new level of customization to your data exploration, offering: * **Enhanced temporal precision:** Our upgraded Time Series Widget empowers you with precise control over temporal data aggregation. You can now extract insights using custom time intervals and enjoy greater granularity, resulting in more accurate analyses. * **Analysis of multiple time series:** Unlock the ability to analyze multiple time series simultaneously within the widget, enabling seamless concurrent analysis over time.

{% endupdate %} {% update date="2023-09-30" tags="new,workflows" %} ## New components in Workflows for data enrichment, statistics and retail analytics We have released a new set of components in Workflows for **Data Enrichment**: * [Enrich Points](/carto-user-manual/workflows/components/data-preparation#enrich-points) * [Enrich Polygons](/carto-user-manual/workflows/components/data-preparation#enrich-polygons) * [Enrich H3 Grid](/carto-user-manual/workflows/components/data-preparation#enrich-h3-grid) * [Enrich Quadbin Grid](/carto-user-manual/workflows/components/data-preparation#enrich-quadbin-grid) Each of them allows to enrich different types of geospatial data, and all of them allow using both a [Data Observatory](/carto-user-manual/data-observatory) subscription or a custom table as source for the enrichment data. Additionally, we have released a new component for advanced **Statistics** and for **Retail Analytics**, initially supported in Google BigQuery: * [Geographically Weighted Regression](/carto-user-manual/workflows/components/statistics#gwr-grid) * [Commercial Hotspots](https://github.com/CartoDB/gitbook-documentation/blob/master/whats-new/broken-reference/README.md) These additions to Workflows will make it a lot easier to leverage data enrichment and advanced statistical capabilities in CARTO, integrating these complex processes as just another step in a workflow. {% embed url="" %} {% endupdate %} {% update date="2023-09-07" tags="improvement,carto-for-developers" %} ## Leveraging SSO in applications built with CARTO Developers building applications with CARTO can now leverage their existing [Single Sign-On (SSO)](/carto-user-manual/settings/sso) integration enabled in their organization to authenticate users. Given the right setup, these applications will now be able to manage existing users and also first-time users coming from the SSO Identity Provider (IdP) that didn't exist previously in CARTO. The experience for these new users is seamless, without any action or step required. This is an extension of the [Just-in-time provisioning](/carto-user-manual/settings/sso#just-in-time-provisioning) setting available in CARTO Workspace. The changes needed to fully leverage SSO and Just-in-time provisioning are covered: * **For custom applications:** in a new [Build a private application using SSO](/carto-for-developers/guides/build-a-private-application-using-sso) guide. * **For new and existing CARTO for React applications:** in the [Authentication](/carto-for-developers/carto-for-react/guides/authentication-and-authorization) guide. {% embed url="" %} {% endupdate %} {% update date="2023-09-05" tags="new,workflows" %} ## Data Observatory subscriptions as data sources in Workflows We have just made [Data Observatory](/carto-user-manual/data-observatory) subscriptions available in the Data Sources panel in Workflows. This will make premium and public datasets a lot easier to work with: just drag and drop your available samples or subscriptions to the canvas and start building your workflow. With this new addition to Workflows, the largest catalog of curated geospatial datasets is readily available to be integrated with your cloud native analytical pipelines with just a few clicks. Check this new feature documentation [here](/carto-user-manual/workflows/data-sources#data-observatory-subscriptions-as-data-sources). {% embed url="" %} {% endupdate %} {% update date="2023-09-04" tags="new,builder" %} ## Richer descriptions for Builder maps We're delighted to announce the next level of map description functionality in CARTO Builder: Richer map descriptions with support for Markdown. This upgrade takes our previous map description feature to a whole new level. With the new richer map descriptions, you're not just adding text; you're crafting a more engaging user experience. The support for Markdown syntax allows you to include various text formats, headers, links, images, and even bullet-point lists, elevating the user's understanding and interaction with your map. To learn how to add Richer Map Descriptions to your maps, [click here](/carto-user-manual/maps/map-description).

{% endupdate %} {% update date="2023-08-09" tags="new,builder" %} ## Support for Numeric SQL Parameter \ We're thrilled to unveil our newest addition to CARTO Builder - the Numeric SQL Parameter, expanding our portfolio of supported SQL parameter types. This innovative feature offers users enhanced interaction with numerical data within Builder. Leveraging the Numeric SQL parameter, users can seamlessly **retrieve single or pair numeric values from a Control UI** to update the underlying data sources. It's an excellent option for those requiring to filter data by specific numeric ranges or adjusting analytical outputs based on numerical inputs. Learn more about how to set up and use SQL Parameters in your maps [here](/carto-user-manual/maps/sql-parameters).

{% endupdate %} {% update date="2023-07-24" tags="new,workspace" %} ## Sharing controls for Applications We have added the possibility to control the visibility of [Applications](/carto-user-manual/applications) in CARTO through the usual sharing options (private, entire organization...), including the ability to share an application only with specific groups of users. This is especially interesting to customize what applications are shown for each user in the CARTO Workspace depending on the groups that they belong to, and also to start developing applications privately, without the app shortcut being shown to other users. You will find more information for these use cases and other details in the [Managing Applications](/carto-user-manual/developers/managing-credentials) section in this documentation.

{% endupdate %} {% update date="2023-07-20" tags="improvement,workspace" %} ## Mapping groups to user roles in CARTO Administrators in CARTO now have the possibility to **automatically assign a role to their users based on the groups that they belong to**. To do so, just enable this feature and map each group to a user role. For example, you can map the group `acme_data_analysts` to get the editor role in CARTO, and new users belonging to that group will automatically get the editor role as well. This is a powerful approach to quickly onboard dozens or hundreds of users into CARTO while maintaining effortless and enterprise-grade controls over the privileges of each user. [Learn more about mapping groups to user roles](/carto-user-manual/settings/users-and-groups/mapping-groups-to-user-roles).

{% endupdate %} {% update date="2023-07-13" tags="new,workspace" %} ## Viewer credentials mode when sharing BigQuery connections Previously, whenever you created a BigQuery connection using OAuth ("Sign in with Google") it had to remain private, to prevent other users from impersonating your personal credentials. With the addition of the new [**viewer credentials**](/carto-user-manual/connections/sharing-a-connection#require-viewer-credentials) mode when sharing connections, we're unlocking several benefits for organizations using BigQuery: * Now you can [collaborate in maps](/carto-user-manual/maps/sharing-and-collaboration#collaborative-maps) using a shared BigQuery OAuth connection * Instead of creating one connection per user, you can create just one connection and share it with everyone, with fewer management issues. * By requiring viewer credentials, you can leverage [row-level security and other policies](/carto-user-manual/connections/sharing-a-connection#row-level-security-and-other-policies) set in your data warehouse.

{% endupdate %} {% update date="2023-07-06" tags="new,builder" %} ## Search locations by latitude and longitude in Builder We are thrilled to introduce the enhanced [Search Location Bar](/carto-user-manual/maps/search-locations#address-search-bar), formerly known as the *Address Search Bar*. This feature now includes the ability to search for locations using coordinates. Simply input latitude and longitude values, and instantly visualize the corresponding location on the map. Whether you're exploring remote areas, analyzing specific points of interest, or seeking valuable insights, our coordinate search feature empowers you to navigate with precision and seamlessly uncover new possibilities.

{% endupdate %} {% update date="2023-06-30" tags="new,workflows" %} ## Explain your Workflows with rich markdown notes and custom node names We have just added a couple of new features in Workflows that are going to improve a lot the explainability of your multi-step analytical pipelines. * Rich notes supporting [Markdown](https://www.markdownguide.org/basic-syntax/) syntax. * Update nodes with more relevant and descriptive names. {% embed url="" %} {% endupdate %} {% update date="2023-06-30" tags="improvement,workspace" %} ## Remove CARTO footer from public and embedded maps Starting today, users with the ability to customize branding and appearance can also remove the CARTO brand and social icons from their public and embedded maps. This is a setting that is applied to all maps created in the organization. Additionally, administrators can decide whether new users receive the generic CARTO onboarding materials, to further customize the experience for new users. [Learn more about how to activate these customizations](/carto-user-manual/settings/customizations/customizing-appearance-and-branding).

{% endupdate %} {% update date="2023-06-27" tags="new,builder" %} ## Custom aggregation operations for Formula Widget We are excited to introduce the latest enhancement to the [Formula Widget](/carto-user-manual/maps/widgets/formula-widget) in Builder, which allows users to create their own custom aggregation operations. This new feature provides advanced capabilities for users to tailor calculations and derive precise insights from their data using SQL Expressions. With custom aggregation operations, users have the flexibility to define calculations that align precisely with their unique analytical requirements. They can incorporate business-specific formulas and apply complex mathematical operations to single or multiple columns from their data source. This level of customization empowers users to unlock valuable insights and perform advanced calculations that go beyond standard aggregations.

{% endupdate %} {% update date="2023-06-26" tags="new,workflows" %} ## Define geospatial inputs by drawing custom features in Workflows While working with Workflows, in some occasions a component needs to be defined as a custom geography (point, line or polygon). This is currently the case with "[*Table from GeoJSON*](https://docs.carto.com/carto-user-manual/workflows/components/parsers#table-from-geojson)" but this tool will also be used in other components that might need a custom geospatial input. We have developed a new tool, accessible through the "*Draw features*" button to define custom geographies as inputs for components. This new tool come in quite handy in cases where one or more steps in an analysis have to be defined by a manual input, allowing faster prototyping a providing a much better user experience. {% embed url="" %} {% endupdate %} {% update date="2023-06-20" tags="improvement,workspace" %} ## Define a custom schema when importing files When importing geospatial data to a cloud data warehouse, one of the challenges is to select the correct data type for each of the columns in the file, also known as schema. And in most cases, CARTO automatically does the job for you, because we analyze a sample of the data and infer the data type from it. For those cases where the automatic detection isn't exactly what you need, CARTO now allows you to **manually defined the schema of the imported file,** both through CARTO Workspace and Builder, and through our [Imports API](/carto-for-developers/reference/carto-api). An example where this new feature is useful is when dealing with postal codes, that depending on the country could be automatically detected as numbers instead of strings — it doesn't make sense to calculate the *average* postal code. To read more about how to select a custom schema in your imports, read our [Importing data documentation](/carto-user-manual/data-explorer/importing-data).

{% endupdate %} {% update date="2023-06-14" tags="new,workflows" %} ## New batch of components to enable more powerful workflows and provide further flexibility in data transformation pipelines We have released a new batch of components in Workflows to keep increasing the possibilities and the value of this tool to enable the creation of data pipelines and spatial analyses for our users. The majority of components in this new batch are oriented towards providing more flexibility when manipulating and getting your data ready for the analysis. Here's the list of new components: * Multi-Col Formula: it computes new values based on a given expression and a set of fields to apply the expression to; * Multi-Row Formula: it creates a new table containing a new column computed using a multi-row formula based on one or several input columns; * Find Replace: it finds a string in one column of a table and replaces it with the specified value from another table; * Refactor columns: it refactors the columns in a table, allowing to change names and data types, and to select only certain columns from a table; * Transpose: it rotates table columns into rows; * Text to Columns: it adds new columns based on splitting the text string in a text column; * Unique: it separates unique rows and duplicated rows; * Row Number: it creates a new table with an additional column containing row numbers; * Quadbin To Parent: it adds a new column named quadbin\_parent with the value of the parent quadbin at a specific resolution; * H3 To Parent: it adds a new column named h3\_parent with the value of the parent h3 at a specific resolution; * H3 KRing: it returns the neighboring indexes in all directions under the K distance size; * H3 Distance: it computes the H3 grid distance between two H3 index column.

{% endupdate %} {% update date="2023-06-06" tags="new,analytics-toolbox" %} ## New function to generate point-to-point routes for different transportation modes in the Analytics Toolbox for BigQuery, Snowflake and Redshift In the lds module of the last release of the [Analytics Toolbox](https://docs.carto.com/data-and-analysis/analytics-toolbox-overview) for BigQuery, Snowflake and Redshift we have now added the function to CREATE\_ROUTES between given sets of origins and destinations (points) in a query, supporting different transportation modes and other advanced parameters. The function generates a new table with the columns of the input query plus a column with the resulting routes. Note that the routes are calculated by calling one of our external location data services providers. This functionality is also available from CARTO’s [LDS API](/carto-for-developers/reference/carto-api).

{% endupdate %} {% update date="2023-06-06" tags="new,analytics-toolbox" %} ## Space-time cluster analysis now available in the Analytics Toolbox for BigQuery In the last release of the [Analytics Toolbox for BigQuery](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery) we have available a new set of functions in order to perform space-time cluster analysis, for when data has both a spatial and a temporal component and you want to identify clusters looking at both dimensions at the same time (e.g. hotspots of demand for food delivery services in different periods of the day). Our implementation computes the space temporal Getis-Ord Gi\* statistic for each area and timestamp according to the method described in this [paper](https://www.tandfonline.com/doi/abs/10.1080/00330124.2019.1709215?journalCode=rtpg20). This is supported now with two new functions in the [statistics module](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/statistics) of the toolbox, namely [GETIS\_ORD\_SPACETIME\_QUADBIN](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/statistics#getis_ord_spacetime_quadbin) for quadbin indexes and [GETIS\_ORD\_SPACETIME\_H3](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/statistics#getis_ord_spacetime_h3) for H3 indexes.

{% endupdate %} {% update date="2023-05-16" tags="new,builder" %} ## Focus maps on user's device location Finding your current location on CARTO maps is finally possible. This feature is specially helpful when users require the map zoom in to their current position in a seamlessly manner to obtain insights from their surroundings. This is how it works: 1. Click the Focus on User's Device Location button. 2. Enable Location Services on your browsers if required. The map display zooms in to your current location and a blue icon indicates your position on the map. {% embed url="" %} {% endupdate %} {% update date="2023-05-08" tags="improvement,workspace" %} ## Access to the CARTO Data Warehouse SQL console The [CARTO Data Warehouse](/carto-user-manual/connections/carto-data-warehouse) is a connection that comes pre-created for every CARTO organization, and it's fully managed by CARTO. Until this release, it wasn't possible to manage the data available to this connection other than what was already available through Builder and Workflows. Now, all users can introduce a *Google account* that they'll use to access the console. Once inside, you can run any SQL query, copy and edit existing tables or use other built-in features to import and migrate your data. Read more on [how to get access to the CARTO Data Warehouse console](/carto-user-manual/connections/carto-data-warehouse#accessing-the-console).

{% endupdate %} {% update date="2023-05-05" tags="new,analytics-toolbox" %} ## New module in the Analytics Toolbox for Snowflake providing access to a set of geostatistical functions Users of our [Analytics Toolbox for Snowflake](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-snowflake) have now access to a new module named “statistics” offering functions to compute statistical measures on top of your spatial data. In this last release we have added support for computing the [Moran’s I spatial autocorrelation](https://en.wikipedia.org/wiki/Moran's_I) and the Getis-ord Gi\* statistics used for the identification of hotspots based on an input feature.

{% endupdate %} {% update date="2023-05-05" tags="new,analytics-toolbox" %} ## Support for operating with H3 indices in the Analytics Toolbox for PostgreSQL In this last release of the [Analytics Toolbox for PostgreSQL](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-postgresql), we have added a new module named “h3” with a set of functions providing users support for operating over the [H3](https://h3geo.org/) spatial index. H3 is a multi-resolution hexagonal global grid system with hierarchical indexing developed by Uber, offering important benefits when performing spatial analytics at scale. To learn more about Spatial Indexes and H3 in particular, please have a look at our [Spatial Indexes 101](https://go.carto.com/report-spatial-indexes-101) report and our [documentation](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-postgresql/key-concepts/spatial-indexes).

{% endupdate %} {% update date="2023-05-05" tags="new,analytics-toolbox" %} ## New functions to compute the “Area of Applicability” of a model built with BigQuery ML in the Analytics Toolbox for BigQuery Some areas due to their intrinsic characteristics or the data available are not suitable for running the predictive models given the large differences within the data used when training those models (e.g. training a model on big cities and then running predictions in areas of low population density). We have added new functions in the [statistics](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/statistics) module to allow users to compute the Area of Applicability (AOA) of a BigQuery ML model. It generates a metric which tells the user where the results from a Machine Learning (ML) model can be trusted when the predictions are extrapolated outside the training space (i.e. where the estimated cross-validation performance holds). In the case of our [Analytics Toolbox for BigQuery](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery), this functionality is particularly useful when working with our [BUILD\_REVENUE\_MODEL](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/retail#build_revenue_model) and [PREDICT\_REVENUE\_AVERAGE](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/retail#predict_revenue_average) procedures of the [retail](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/retail) module.

{% endupdate %} {% update date="2023-04-24" tags="new,builder" %} ## Support for SQL Parameters in Builder SQL Parameters are placeholders that can be used on any SQL Query data source in Builder. Once defined, the actual value for the parameter can be set through a control UI in the right side panel’s '*Parameters*' tab. This allows to manipulate the actual SQL Query through an UI, by both Editor and Viewer users. Among many different use cases, some applications for this new feature are: * Create 'Text' or 'Dates' parameters. * Reduce the size of a data source before rendering the map. * Allow viewer users to define custom values in the data source in a controlled way. * Use the same parameter in one or more queries. * Filter a dataset before aggregating it to a spatial index grid (H3 or Quadbin). Learn more about how to set up and use SQL Parameters in your maps [here](/carto-user-manual/maps/sql-parameters). {% embed url="" %} {% endupdate %} {% update date="2023-04-21" tags="new,workspace" %} ## Easier authentication for developers with our API Access Tokens UI Developers looking to create geospatial applications at scale usually face an authentication challenge: how to build the application so that data is accessed in a granular and secure way. And there are different solutions depending on your needs: from static API Access Tokens for simple, public applications to dynamic authentication using the CARTO login (with or without Single Sign-On). Today we're making the creation and management of **API Access Tokens** much simpler, with a **complete user interface to create, edit and delete tokens**. API Access Tokens are now the recommended method to start working with [CARTO for deck.gl](https://github.com/CartoDB/gitbook-documentation/blob/master/carto-for-developers/key-concepts/carto-for-deck.gl) and the CARTO APIs, and we've updated the documentation and [API reference](/carto-for-developers/reference/carto-api) accordingly. Learn here [how to create and manage your API Access Tokens](/carto-user-manual/developers/managing-credentials/api-access-tokens).

{% endupdate %} {% update date="2023-04-13" tags="new,workspace" %} ## Optimize your data for geospatial analysis in just a few clicks with our Table Optimization wizard CARTO is the ideal solution for geospatial visualization and analysis of large scale datasets, due to the scalability of the cloud data warehouses (eg: BigQuery, Snowflake, Redshift, Databricks...). However, dealing with such large datasets requires special attention into performance and optimizations. Now, whenever we detect that one of your tables could perform better according to our [performance considerations](/carto-user-manual/maps/performance-considerations), we'll show a warning in Data Explorer and Builder, and you'll be able to take action immediately. In just a few clicks, **you'll overwrite or generate an optimized copy of your data**, that will perform faster and save computing costs. To understand in detail how these optimizations work, head to the [Optimizing your data](/carto-user-manual/data-explorer/optimizing-your-data) guide.

{% endupdate %} {% update date="2023-04-10" tags="new,workspace" %} ## Default role for new users and SSO just-in-time provisioning We are adding two new features for admins to manage new users more easily and predictably: * **Default role for new users**: Admins can now choose which role should be applied to new users, and by default it will be set to "viewers" following the least-privilege principle. Find more information about [roles in CARTO](/carto-user-manual/settings/users-and-groups/managing-user-roles) and [about this setting](/carto-user-manual/settings/users-and-groups/managing-user-roles#default-role-for-new-users). * **SSO Just-in-time provisioning:** Admins that have integrated their own SSO login can now decide whether new users will get additional questions when onboarding or not. If it's enabled, we'll just provision their user as soon as they login, without any needed step. This new setting has been included in the [documentation about SSO at CARTO](/carto-user-manual/settings/sso).

{% endupdate %} {% update date="2023-04-06" tags="new,builder" %} ## Supporting labels in tile layers CARTO Builder now supports adding labels to point layers loaded via tiles, with a set of improved features: * Support for primary and secondary label on each point. * Now using a better typography, increasing readability. * Collision control: Now labels are displayed in a way that they don’t collision with each other, adapting dynamically on each zoom level. * Custom colors for the font and outline, allowing much better customization capabilities.

{% endupdate %} {% update date="2023-04-03" tags="new,analytics-toolbox" %} ## Enabling users to create spatial scores using the Analytics Toolbox for BigQuery In this month's release of the Analytics Toolbox for BigQuery, we have published a new functionality that consists of a set of procedures within the statistics module to enable users to [create spatial scores](https://academy.carto.com/advanced-spatial-analytics/spatial-analytics-for-bigquery/step-by-step-tutorials/how-to-create-a-composite-score-with-your-spatial-data) (also known as [composite indicators](https://www.oecd.org/sdd/42495745.pdf) or indexes) derived from a combination of different features. We have included 3 different procedures: * [CREATE\_SPATIAL\_COMPOSITE\_SUPERVISED](/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/statistics#create_spatial_composite_supervised): to compute a spatial composite score as the residuals of a regression model which is used to detect areas of under- and over-prediction. * [CREATE\_SPATIAL\_COMPOSITE\_UNSUPERVISED](/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/statistics#create_spatial_composite_unsupervised): to perform an aggregation of individual variables, scaled and weighted accordingly, into a spatial composite score. * [CRONBACH\_ALPHA\_COEFFICIENT](/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/statistics#cronbach_alpha_coefficient): to measure the internal consistency of the variables used to derive the spatial composite score.

{% endupdate %} {% update date="2023-03-28" tags="improvement,workspace" %} ## Introducing a new Usage quota and a new Location Data Services credits system In order to give more flexibility to our users, we have removed a lot of the quotas that were feature-specific, such as *maps, public maps, apps* or *connections,* and we have replaced them with a combined usage metric, the **Usage quota**, that will be the main driver of consumption for all new customers through the CARTO platform. The Usage quota is related to the number of successful API calls, excluding the metadata. Learn more about how it's calculated and how it applies to your subscription in our [documentation](/carto-user-manual/settings/quotas-and-rate-limits/understanding-your-organization-quotas#usage-quota). Additionally, we have changed the way **LDS credits** are calculated. Before, they were monthly and separated by service: geocoding and isolines. Now, we've combined them into a single annual quota that results in more capacity and better flexibility.

{% endupdate %} {% update date="2023-03-14" tags="improvement,workspace" %} ## Importing geospatial files into Amazon Redshift using CARTO Starting today, CARTO supports [importing geospatial files](/carto-user-manual/data-explorer/importing-data) through an **Amazon Redshift** connection leveraging the [CARTO Import API](/carto-for-developers/reference/carto-api). With this new functionality, CARTO users working with Amazon Redshift will be able to quickly get their geospatial data ready for advanced analysis and visualization, from no-code tools like Builder or Workflows to geospatial development libraries such as CARTO for deck.gl. Additionally, we are giving all customers the option to [configure the AWS S3 Bucke](/carto-user-manual/settings/advanced-settings/configuring-s3-bucket-for-redshift-imports)t used to import files (instead of the default bucket provided by CARTO in cloud instances).

{% endupdate %} {% update date="2023-03-07" tags="new,analytics-toolbox" %} ## Merchant universe matching analysis to understand market penetration for CPG players available in the Analytics Toolbox for BigQuery In this month's release of the Analytics Toolbox for BigQuery, we have published a new functionality within the [CPG module](/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/cpg) that allows our users to perform the merchant universe matching analysis in order to derive insights on market penetration and to identify expansion opportunities. With this analysis, CPG players can match their current universe of merchants/customers against the total universe of all potential ones on a given market, in order to identify in which merchants their products are still not present. This analysis is performed with two new procedures in the Analytics Toolbox: [UNIVERSE\_MATCHING](/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/cpg#universe_matching) which performs a fuzzy match between two POI datasets based on location and name similarity, and [UNIVERSE\_MATCHING\_REPORT](/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/cpg#universe_matching_report) that generates report-like tables summarizing market penetration insights.

{% endupdate %} {% update date="2023-03-03" tags="new,builder" %} ## New Builder SQL Analyses available for Redshift and Snowflake connections A set of new analyses have been added to Builder, to reach the same level of support on different data warehouses: * **Create buffers:** Available now for Redshift and Snowflake connections. * **Intersect and aggregate:** Available now for Snowflake connections. * **K-means clustering:** Available now for Redshift and Snowflake connections. Check the list of analyses available for each data warehouse and further documentation about each of them [here](broken://pages/sWKFdHIhTix6GB8GTYY1). {% endupdate %} {% update date="2023-02-24" tags="beta,workflows" %} ## Enabling users to share workflows with their organization From today, users can start [sharing workflows](/carto-user-manual/workflows/sharing-workflows) with the rest of users within their CARTO organization; who will then be able to open the shared workflow in view mode, and in the case of Editor users duplicate the workflow and edit the copied version as they wish. Additionally, we have adapted the Workflows main page in the Workspace to allow searching workflows and managing the existing ones, in line with what’s available in the Maps section. {% embed url="" %} {% endupdate %} {% update date="2023-02-01" tags="beta,workflows" %} ## CARTO Workflows in public beta now with support for Snowflake, Redshift and PostgreSQL From today, customers on Snowflake, Redshift and PostgreSQL have the possibility to use the public beta version of CARTO Workflows with data sources from their data warehouse connections. Note that CARTO Workflows is a new tool that enables users of all types and skill levels to harness the power of cloud data warehouses, [spatial SQL](https://carto.com/spatial-sql/), and advanced spatial analytics. To learn more about this new development, please check our [product documentation](/carto-user-manual/workflows).

{% endupdate %} {% update date="2023-01-31" tags="beta,analytics-toolbox" %} ## New functions to generate routing matrices and isolines natively in BigQuery In the January 2023 release of the Analytics Toolbox for BigQuery, we have published a new and improved version of the [`routing`](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/routing) module. This new version includes procedures [`ROUTING_MATRIX`](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/routing#routing_matrix) to calculate origin-destination matrices and [`ROUTING_ISOLINES`](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/routing#routing_isolines) to compute isolines around a set of locations, both supporting multiple transportation modes (car, bike, and walk). These new functions run on top of [CARTO’s road network](https://carto.com/spatial-data-catalog/browser/geography/cdb_road_networ_81badfc2/) (derived from OSM segments) that is available as a public subscription in the [Data Observatory](https://docs.carto.com/data-and-analysis/data-observatory/overview/getting-started). Please note that these improvements imply breaking changes with the previous version of the routing module. To learn more about these new procedures please check our [product documentation](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/routing). We have also published a [guide](https://academy.carto.com/advanced-spatial-analytics/spatial-analytics-for-bigquery/step-by-step-tutorials/using-the-routing-module) to illustrate how to benefit from this module of the Analytics Toolbox.

{% endupdate %} {% update date="2023-01-31" tags="beta,analytics-toolbox" %} ## Adding raster support in BigQuery with a new module in the Analytics Toolbox In the January 2023 release of the Analytics Toolbox for BigQuery, we have launched in beta our new [`raster`](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/raster) module. This feature offers a set of functions to operate with raster data natively in BigQuery, benefiting from the processing speeds and scalability of this data warehouse. Alongside the raster module in the Analytics Toolbox, we have also made available our [Raster Loader](https://raster-loader.readthedocs.io/en/latest/), built in collaboration with [Makepath](https://makepath.com/). This publicly available Python library works as a tool for loading and optimizing GIS raster data into cloud-based data warehouses. In order to learn more about this new module please check our [product documentation](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/raster). We have also published an [example](https://academy.carto.com/advanced-spatial-analytics/spatial-analytics-for-bigquery/step-by-step-tutorials/using-raster-and-vector-data-to-calculate-total-rooftop-pv-potential-in-the-us) that illustrates how to use some of our functionality to combine raster and vector data to solve a spatial analysis.

{% endupdate %} {% update date="2023-01-26" tags="new,workspace" %} ## New space for private data available for every user in the CARTO Data Warehouse Starting with this release, users that explore their CARTO Data Warehouse connection in [Data Explorer](/carto-user-manual/data-explorer) will find two datasets (represented as folders) inside their organization data: **private** and **shared**. The new dataset *"private"* is a unique dataset for each user, and all the tables and tilesets in this dataset will **only be available to that user**. Private datasets have a unique qualified name that identifies the user, extracted from their email. The "*shared*" dataset will remain available to all the editor users in that organization. You can find all the documentation for this feature in the [CARTO Data Warehouse documentation](/carto-user-manual/connections/carto-data-warehouse#private-private).

{% endupdate %} {% update date="2023-01-24" tags="improvement,builder-workspace" %} ## Search, list view and breadcrumbs when browsing your data in Builder and Workspace An important step of most processes in CARTO is to browse and select data sources and data locations: * A data source (eg: adding a [source in Builder](/carto-user-manual/maps/data-sources), using a [SQL Analysis](broken://pages/sWKFdHIhTix6GB8GTYY1)...) * A future location to save results (eg: [creating a tileset](https://github.com/CartoDB/gitbook-documentation/blob/master/whats-new/broken-reference/README.md), [importing data](/carto-user-manual/data-explorer/importing-data), [running an enrichment](https://github.com/CartoDB/gitbook-documentation/blob/master/whats-new/broken-reference/README.md)...) We have improved the user experience for these cases by **adding a search bar** that works at every level of your data, **adding a new view: the list view,** and adding **breadcrumbs** to help you navigate your data. The list view is similar to the one used in [Data Explorer](/carto-user-manual/data-explorer) (including the search bar and breadcrumbs) and will now make the experience more consistent across the CARTO platform. If you would rather focus on the hierarchy of your data, the tree view is still available on the top right. This is especially beneficial if you have a large number of projects/databases, schemas/datasets, or tables and tilesets: where previously you would need to scroll indefinitely, now you can perform a quick search. {% embed url="" %} {% endupdate %} {% update date="2023-01-23" tags="new,builder" %} ## Dynamic aggregation of point layers into Quadbin grids With this new feature, point layers can be [transformed dynamically into an aggregated grid](https://docs.carto.com/carto-user-manual/maps/layer/layer-styles#dynamic-aggregation-of-points-into-quadbin-grids) leveraging our Quadbin spatial index. This produces a very significant increment in performance, but also allows aggregating data from the original features to make sure that all data is taken into consideration. Some highlights: * Available for all point tile layers from all data warehouses * Implemented with pure SQL in our Maps API, no external dependencies such as the Analytics Toolbox or third-party libraries. * It allows aggregating properties from the original points and also the number of points per cell. * Inherits all the advantages and features of the previously existing Spatial Index layers. * The aggregation happens transparently so no need to manually type any SQL code to aggregate the points. {% embed url="" %} {% endupdate %} {% update date="2023-01-18" tags="beta,workflows" %} ## CARTO Workflows in public beta with support for Google BigQuery and CARTO Data Warehouse Today we are excited to announce that CARTO Workflows is now publicly available in beta with support for Google BigQuery and CARTO Data Warehouse. CARTO Workflows is a new tool that enables users of all types and skill levels to harness the power of cloud data warehouses, [spatial SQL](https://carto.com/spatial-sql/), and advanced spatial analytics. CARTO Workflows provides a visual language to design and execute multi-step spatial analytics procedures, reducing the complexity and the high dependance on specialist knowledge to leverage the power of location intelligence. To learn more about this new development, please check our [product documentation](/carto-user-manual/workflows). In the coming weeks we will add support to run CARTO Workflows on Snowflake, Redshift and PostgreSQL-based data warehouses, if you want to know more about that please contact us through our [Support team](/faqs/support-packages). {% embed url="" %} {% endupdate %} {% update date="2023-01-18" tags="improvement,documentation" %} ## New documentation layout Our documentation portal just got a new look and feel! This new layout should provide the following benefits: * Cleaner look that uses more screen space if available * A search bar to quickly find content * All the documentation is organized and available on the left menu * All pages now have an "*On this page*" index on the right sidebar \_\_ to quickly locate sections Hopefully, you'll have a better experience using this documentation. If you have any feedback about it, contact us through our [Support team](/faqs/support-packages). We'll keep working on documentation improvements during the following weeks.

{% endupdate %} {% update date="2023-01-13" tags="new,builder" %} ## Multiple editor users working on the same map Collaborating on CARTO maps is finally possible, in asynchronous mode. This is helpful in setups such as production-ready maps, where the original owner might be out of the office; or in situations where the data, analysis, and cartography are each accomplished by different users. This is how it works: 1. The map owner first needs to **enable collaboration** for that map. 2. From that moment, all editors with access to the map will be able to edit it. 3. If two editors try to edit at the same time, the last one will be locked out, with the option of requesting to take over editing. Happy collaboration! {% embed url="" %} {% endupdate %} {% update date="2022-12-29" tags="new,builder" %} ## Builder SQL Analyses available for PostgreSQL connections Customers relying on [PostgreSQL](https://www.postgresql.org/) and [PostGIS](https://postgis.net/) for their geospatial data will now be able to create and execute analyses directly from Builder. These analyses are created as dynamically generated SQL queries that are pushed down to a PostgreSQL database through a [CARTO connection](https://docs.carto.com/carto-user-manual/connections/creating-a-connection/#connection-to-postgresql). The result can be visualized, used as input for another step of the analysis, or persisted into a new table. {% embed url="" %} {% endupdate %} {% update date="2022-12-27" tags="improvement,analytics-toolbox" %} ## Additional options to configure the creation of isolines in the Analytics Toolbox In the last release of the Analytics Toolbox for [BigQuery](https://docs.carto.com/analytics-toolbox-bigquery/release-notes/), [Snowflake](https://docs.carto.com/analytics-toolbox-snowflake/release-notes/) and [Redshift](https://docs.carto.com/analytics-toolbox-redshift/release-notes/) we have added the possibility to configure more options as parameters when executing the functions to CREATE\_ISOLINES. These new options, which depend on the LDS service provider, allow the user to configure more transportation modes such as truck or bike, the possibility of specifying departure or arrival times allowing the creation of reverse isolines, and other options like different routing modes. Additionally, we have added new confidence/relevance metadata to the results of the geocoding function GEOCODE\_TABLE.

{% endupdate %} {% update date="2022-12-27" tags="improvement,workspace" %} ## Importing geospatial files into PostgreSQL databases through CARTO Workspace CARTO Workspace now supports [importing geospatial files](https://docs.carto.com/carto-user-manual/data-explorer/importing-data/) through a PostgreSQL connection leveraging [CARTO Import API](/carto-for-developers/reference/carto-api). With this new functionality, CARTO users working with a PostgreSQL database will be able to get their geospatial data ready for advanced analysis and visualization in Builder and [CARTO for deck.gl](https://docs.carto.com/deck-gl/getting-started/). {% endupdate %} {% update date="2022-12-27" tags="beta,analytics-toolbox" %} ## New function to identify similar locations, such as merchants or stores, based on the characteristics of their trade areas in the Analytics Toolbox for BigQuery We have released within the [cpg module](https://docs.carto.com/whats-new/analytics-toolbox-bigquery/sql-reference/cpg/) of the [Analytics Toolbox for BigQuery](https://docs.carto.com/analytics-toolbox-bigquery/overview/getting-started/) a new function named [FIND\_SIMILAR\_LOCATIONS](https://docs.carto.com/analytics-toolbox-bigquery/sql-reference/cpg/#find_similar_locations) that allows users to identify which locations (e.g. merchants, stores) are more similar to a chosen location (e.g. top performant) based on the characteristics of their surrounding areas (or trade areas), which can be configured to be based on demographic features, environmental, nearby points of interest, footfall, etc. In [this example](https://docs.carto.com/analytics-toolbox-bigquery/examples/similar-locations-iowa/) we illustrate how to use this new analysis function to solve the aforementioned use-case.

{% endupdate %} {% update date="2022-12-05" tags="improvement,workspace" %} ## Improvements for Google BigQuery connections: re-connect and billing project We’ve improved some scenarios for users who created a [Google BigQuery connection](https://docs.carto.com/whats-new/carto-user-manual/connections/creating-a-connection/#connection-to-bigquery): * Now CARTO should behave smoothly when your credentials *(Service Account or OAuth)* have access to **more than 2000 projects**. You should be able to select any of them as your billing project, and the Data Explorer will also let you explore all of them in a quick search. * Now it’s possible to **repair Google OAuth connections**. Before, if you connected using “Sign in with Google” (often referred as OAuth), this connection could break after this authorization is revoked. This could happen automatically after changing your password, for example. Using the new re-connect flow will authorize CARTO again in the same connection, so all your maps will continue working as usual. {% endupdate %} {% update date="2022-11-29" tags="beta,analytics-toolbox" %} ## Assisted process to install the Analytics Toolbox for Snowflake from the CARTO Workspace Today we are making available the option for Admin users to install the Analytics Toolbox in their Snowflake accounts with a simplified process assisted by the CARTO UI. From the Settings section of the CARTO Workspace users can now install, update and uninstall the [Analytics Toolbox for Snowflake](https://docs.carto.com/analytics-toolbox-snowflake/overview/getting-started/) without external support. All details for setting up your Snowflake resources and to carry out the installation process can be found in [our documentation](http://docs.carto.com/analytics-toolbox-snowflake/overview/getting-access/#assisted-installation-from-the-carto-workspace). {% embed url="" %} {% endupdate %} {% update date="2022-11-18" tags="new,developer-tools" %} ## Announcing CARTO for React 1.4.7 A new version of [CARTO for React](https://docs.carto.com/react/overview/) has been released with the following main highlights: * Support for parameterized queries. Now, a user can define queries that allow for external parameters to be injected into the query and create more powerful dynamic queries without having to modify the SQL; this, will result in filtering being applied from the backend side to the sources and will be reflected in layers and widgets. For more information, a guide has been included in our documentation and can be accessed [here](https://docs.carto.com/react/guides/query-parameters/). * Several bug fixes. {% endupdate %} {% update date="2022-11-15" tags="new,applications" %} ## Batch simulation of locations in Site Selection application Batch simulation of candidate locations is now possible in the Site Selection application. Instead of simulating locations one by one, users can now use a CSV template to upload in bulk the location details of their candidates. They can subsequently edit and remove their locations in the application as they see fit before running a batch simulation. This feature enables users to process in bulk lists of candidate locations often provided by separate research teams, rather than one by one. {% embed url="" %} {% endupdate %} {% update date="2022-11-15" tags="new,applications" %} ## Feature importance widget for revenue predictions in Site Selection application Users can now explore the impact of the revenue prediction model features directly through the Site Selection application. For each simulated location and associated predicted revenue, the widget showcases the magnitude of the impact of the features included in the model (i.e. population, mobility, POIs, etc.), as well as whether they contribute to predictions positively or negatively. {% embed url="" %} {% endupdate %} {% update date="2022-11-15" tags="new,builder" %} ## Logarithmic scales in Builder Logarithmic scales are now available as a data classification option in Builder. While they’re available for all kind of sources, a logarithmic scales based on powers of `10` will be the default option for [aggregated data sources](https://docs.carto.com/carto-user-manual/maps/data-sources/#aggregated-grids). This new addition will make it easier to create better cartography when working with spatial indexes, as well as a handy additional method of classification for other types of maps.

{% endupdate %} {% update date="2022-11-07" tags="improvement,workspace" %} ## Geocoding, Isolines and Tokens quotas now available for tracking in Workspace Following the release of [geocoding and isolines for Google BigQuery](https://docs.carto.com/whats-new/geocoding-and-isolines-in-google-bigquery/), and the [new layout for the Settings](https://docs.carto.com/whats-new/new-layout-in-settings-section/), we’re adding new trackers for quotas in Workspace so users can understand and predict their consumption. 1. We added a new **“CARTO for Developers”** section, including: * Existing quota: *Applications*, for applications created using Workspace * A new quota: *Tokens*, for tokens generated using the Tokens API 2. We also added a new **“Location Data Services”** section, including tracking for **Geocoding** and **Isolines** operations. These quotas are reset every month, and each unit represents a row processed. 3. Finally, the “Connections” quota was removed, and will be gradually removed so users can create as many connections as needed without any warnings.

{% endupdate %} {% update date="2022-11-07" tags="new,builder" %} ## Resolution selector and aggregation methods for categorical data in spatial index layers Users working with Spatial Indexes data (Quadbin or H3) in Builder have a couple of new additions that will help them create better and more insightful visualizations: * The possibility of adjusting the aggregation resolution for a finer control over the aggregation. * Aggregation operations for categories: `MODE` to get the most frequent category in the aggregated cells; `ANY VALUE` to get *any* of the aggregated categories. {% embed url="" %} {% endupdate %} {% update date="2022-10-27" tags="new,analytics-toolbox" %} ## Visualize very large datasets based on H3 thanks to our support for spatial index tilesets in Databricks Starting today, our Databricks users have the possibility to generate [spatial index tilesets based on H3](https://docs.carto.com/analytics-toolbox-databricks/reference/tiler/#create_spatial_index_tileset) natively in Databricks. The tiler is a module of our advanced Analytics Toolbox for Databricks that allows to process and visualize very large spatial datasets stored in Databricks. If you are interested in it, please contact with to receive more information about it. {% embed url="" %} {% endupdate %} {% update date="2022-10-25" tags="new,analytics-toolbox" %} ## Data Enrichment functions in the Analytics Toolbox for AWS Redshift Users can now enrich their data tables in Amazon Redshift with features from both their Data Observatory subscriptions and from their other 1st party data tables. Procedures for Data Enrichment are now included in the Data module of the Analytics Toolbox for Redshift, specific for working with point data, polygons or spatial indexes. Please check out our [documentation](https://docs.carto.com/analytics-toolbox-redshift/sql-reference/data/#data) to find all the details and examples. {% embed url="" %} {% endupdate %} {% update date="2022-10-18" tags="improvement,workspace" %} ## Improvements and new design in login and signup Continuing our efforts to improve our sign up and login processes, we’re now launching a new experience. Users should be able to join CARTO in a more smooth way with these new additions: * A screen now will offer users the chance to create a new organization or join an existing one if there are users from the same domain. * The list of organizations to join now has details about the users, the plan and a search bar to find the desired organization. * When you [request to join](https://docs.carto.com/carto-user-manual/overview/getting-started/#joining-an-existing-organization) an organization you can now cancel that request (if it was undesired or the admin is unresponsive). * When following an invitation the signup form will now be already pre-filled. * The process to join an organization is now simpler with less steps. * Multiple bug fixes and minor improvements.

{% endupdate %} {% update date="2022-10-18" tags="beta,analytics-toolbox" %} ## Leverage CARTO’s Analytics Toolbox and visualize data natively from your data warehouse without leaving your Python notebook CARTO now provides a set of [Python packages](http://docs.carto.com/carto-python/overview/) to allow data scientists to work with our platform from within Python notebooks. These packages allow users to work with geospatial data in a fully cloud native way without having to leave their Python environment, and taking advantage of all the potential that [Analytics Toolbox](https://docs.carto.com/analytics-toolbox/about-the-analytics-toolbox/) provides to execute advanced spatial analytics in [Spatial SQL](https://carto.com/spatial-sql/) natively within the leading cloud data warehouse platforms. {% embed url="" %} {% endupdate %} {% update date="2022-10-18" tags="private-beta,builder" %} ## Multiple editor users working on the same map {% hint style="info" %} **Update January 13th, 2023:** this feature is now in General Availability and it's available to all CARTO cloud users. [Read all details here](/whats-new#multiple-editor-users-working-on-the-same-map). {% endhint %} Collaborating on CARTO maps is finally possible, in asynchronous mode. This is helpful in setups such as production-ready maps, where the original owner might be out of the office; or in situations where the data, analysis, and cartography are each accomplished by different users. {% endupdate %} {% update date="2022-10-13" tags="new,workspace" %} ## Spatial Index and Point Aggregation tilesets available from Data Explorer Starting today, it is available to all users the possibility of generating both Spatial Index and Point Aggregation tilesets on their own data tables directly from the Data Explorer UI. This feature complements the [existing workflow](https://docs.carto.com/carto-user-manual/data-explorer/creating-a-tileset-from-your-data/), with the possibility of generating tilesets of large datasets based on spatial index (H3 and quadbin) and points, by defining aggregations on the interested features. The platform detects automatically if the table is based on spatial indexes or points and provides the new options in the “Create Tileset” wizard. {% embed url="" %} {% endupdate %} {% update date="2022-10-11" tags="new,builder" %} ## New filter to select date ranges in your temporal data when creating maps in Builder We have just added a new exciting component to Builder. The new [**Date Filter**](/carto-user-manual/maps/sql-parameters) allows you to reduce the size of a data source by selecting a specific time range from a date or timestamp column in your data. It is available for dynamically tiled data sources, which basically means tables bigger than 30MB and Custom SQL queries. Find more information about data source sizes [here](https://docs.carto.com/carto-user-manual/maps/performance-considerations). When dealing with temporal series it is very common to find overlapping points, repeated geometries or spatial indexes… which make the analysis and visualization of the data cumbersome and difficult to visualize. This new component lets the user select a specific time range to filter their data, making all these problems easier to work around. This new filter actually pushes down a SQL filter, which reduces the amount of data processed and transferred, while the [Time-Series widget](/carto-user-manual/maps/widgets/time-series-widget) allows filtering the data when it has already been loaded in the browser. They can play very well together, using the filter to pre-select a time range to work with, and the Time-Series widget for finer client-side filtering, visualizing the series, animations, etc As an Editor, you can decide whether or not to include the Date selector in the public map. This allows deeper data exploration for viewer and public users. {% embed url="" %} {% endupdate %} {% update date="2022-10-06" tags="beta,analytics-toolbox" %} ## New analytical functions to run Customer Segmentation use-cases for the CPG industry We have released in beta a new domain-specific module in the [Analytics Toolbox for BigQuery](https://docs.carto.com/analytics-toolbox-bigquery/overview/getting-started/) to solve advanced geospatial analysis for the CPG / FMCG sector, starting with [customer segmentation](https://docs.carto.com/analytics-toolbox-bigquery/sql-reference/cpg/). We now offer a set of procedures that allow users in that industry to solve this use-case end-to-end, from the generation of trade areas to running multiple segmentation scenarios of merchants based on a customisable set of spatial features. In this [recent blogpost](https://carto.com/blog/trade-area-analysis-cpg-merchants/) we showcase how to use these analytical routines with a specific example.

{% endupdate %} {% update date="2022-09-19" tags="new,builder" %} ## Custom Markers in Builder Now users can include [custom icons as marker](/carto-user-manual/maps/layers/point)[s](/carto-user-manual/maps/layers/point) for point data in Builder maps.This feature includes two differents ways of selecting an icon: * Using one from our preset collection; based on the well-known Maki icon library, which is designed for cartography purposes; * Uploading a custom icon in .png or .svg formats. Different markers can also be defined by the values of a categorical column, and can even be rotated based on a numeric value; which enables different use-cases such as rotating an arrow based on azimuth for telecommunication antennas or the wind direction in weather maps. {% embed url="" %} {% endupdate %} {% update date="2022-09-16" tags="improvement,apis" %} ## Caching performance improvements We have released a few changes in how we cache API requests in the CDN that will produce a significant improvement in the overall performance of the platform; specifically applying to Builder maps and applications developed using our APIs. Learn more about such changes in our documentation for developers in the [CARTO API Reference](/carto-for-developers/reference/carto-api); each end-point in Maps API and SQL API now contains a reference about our caching strategies. In Builder, users have new a couple of new features: * “Refresh data source”: to make sure users get non-cached versions of the data. Note that with this option your map will be skipping the CDN and getting the data each time from your data warehouse. * “Refresh data source every X”: to allow the user to control the update frequency of the data displayed on public maps.

{% endupdate %} {% update date="2022-09-15" tags="improvement,workspace" %} ## New layout in Settings section We have improved the layout in the Settings section in the CARTO Workspace; providing a better way to organize different areas by topic and providing a smoother interface for explaining the different Settings options for your CARTO account.

{% endupdate %} {% update date="2022-09-13" tags="improvement,apis" %} ## Performance improvements in Dynamic Tiling A couple important fixes have been implemented to our [Dynamic Tiling](https://docs.carto.com/carto-user-manual/maps/performance-considerations/#medium-size-datasets-and-sql-queries) strategies. Dynamic Tiling is the technology CARTO has developed to dynamically generate tiles for medium sized dataset and layers loaded as SQL Queries from your cloud data warehouse. * When working with points, many times widgets were not showing data due to our “visual aggregation” strategy when points were very close to each other. We have now removed this type of aggregation, and we are only applying a limit of 200k points per tile to prevent performance issues. If now you encounter widgets not showing data, you just need to zoom in to reduce the number of points per tile. * With our previous strategy some polygons or lines that were falling in the intersection of multiple tiles were splitted for visualization purposes, which was making the same data point count multiple times in widgets. We have solved this problem by asking the user to identify a unique id property for the data source at the time of creating widgets.

{% endupdate %} {% update date="2022-09-07" tags="improvement,workspace" %} ## Improvements in invitation & request management for Admin users As part of an active taskforce to improve our sign up and login processes, we have now released an improved interface for Admin users to [manage invitations](https://docs.carto.com/carto-user-manual/settings/inviting-users-to-your-organization/) to join the CARTO organization and to manage user requests to join it.

{% endupdate %} {% update date="2022-08-26" tags="new,analytics-toolbox,builder,workspace" %} ## Geocoding and isolines in Google BigQuery We are very excited to announce that users of Google BigQuery can now geocode their tables with address data and create trade areas around locations based on drive/walk time isolines natively from their data warehouse. These procedures call external location data service providers such as TomTom, HERE and Mapbox. Please check the [SQL Reference](https://docs.carto.com/analytics-toolbox-bigquery/sql-reference/lds/) of our [Analytics Toolbox for BigQuery](https://docs.carto.com/analytics-toolbox-bigquery/overview/getting-started/) for more details, and also refer to our examples on how to [geocode your data](https://docs.carto.com/analytics-toolbox-bigquery/examples/geocoding-your-address-data/) and [create isolines](https://docs.carto.com/analytics-toolbox-bigquery/examples/trade-areas-based-on-isolines/). Note that these functionalities are also enabled from the Data Explorer and Builder tools. {% embed url="" %} {% endupdate %} {% update date="2022-08-26" tags="new,analytics-toolbox" %} ## Geostatistics functions in the Analytics Toolbox for AWS Redshift Users of AWS Redshift can now access a new set of [geostatistics functions](https://docs.carto.com/analytics-toolbox-redshift/sql-reference/statistics/) to expand the spatial capabilities of their data warehouse with CARTO’s Analytics Toolbox. We have released [Getis-ord Gi\*](https://docs.carto.com/analytics-toolbox-redshift/sql-reference/statistics/#getis_ord_quadbin), [Moran’s I](https://docs.carto.com/analytics-toolbox-redshift/sql-reference/statistics/#morans_i_quadbin) and [p-value](https://docs.carto.com/analytics-toolbox-redshift/sql-reference/statistics/#p_value) methods that can run natively with your data hosted in Redshift. Learn more about these analytical functions in our [product documentation](https://docs.carto.com/analytics-toolbox-redshift/sql-reference/statistics/). {% endupdate %} {% update date="2022-08-05" tags="new,builder" %} ## New Range widget in Builder From today, users of Builder can add a new type of widgets to their interactive maps. The [Range widget](/carto-user-manual/maps/widgets/range-widget) allows you to filter data based on precise numeric ranges. {% embed url="" %} {% endupdate %} {% update date="2022-08-04" tags="new,analytics-toolbox" %} ## Cannibalization Analysis available in the Retail module of the Analytics Toolbox for BigQuery Retailers working with Google BigQuery and CARTO can now analyze the potential cannibalization cased by a set of new stores into their existing networks, based on the overlap of the different trade areas in terms of geographic area but also in terms of any other spatial feature that the user wants to use in the analysis (e.g. population, number of households). Check out [our documentation](https://docs.carto.com/analytics-toolbox-bigquery/sql-reference/retail/#cannibalization_overlap) and [this example](https://docs.carto.com/analytics-toolbox-bigquery/examples/store-cannibalization/) to learn more about how to run this analysis with our [Analytics Toolbox for BigQuery](https://docs.carto.com/analytics-toolbox-bigquery/overview/getting-started/).

{% endupdate %} {% update date="2022-07-28" tags="improvement,builder" %} ## Renaming of data sources in Builder Users can now rename the [data sources](https://docs.carto.com/carto-user-manual/maps/data-sources/#data-sources) added to a Builder map; although seemingly a small product addition, this new feature brings a big improvement in terms of user experience for our users. {% embed url="" %} {% endupdate %} {% update date="2022-07-15" tags="improvement,workspace" %} ## New Data Explorer UI We have introduced a new design in the [Data Explorer](https://docs.carto.com/carto-user-manual/data-explorer/introduction/) that brings a good amount of improvements for our users: it allows to search and sort data objects within connections, provides pagination and infinite scrolling for connections with access to thousands of tables, facilitates access to Data Observatory subscriptions, includes shortcuts for creating new connections and importing data, etc.

{% endupdate %} {% update date="2022-07-15" tags="new,analytics-toolbox" %} ## Spatial Index tilesets for Postgresql Postgresql users can now generate tilesets based on spatial index data (i.e. H3, Quadbin) natively in their databases. This [new functionality](https://docs.carto.com/analytics-toolbox-postgres/sql-reference/tiler/#create_spatial_index_tileset) from our [Analytics Toolbox for Postgresql](https://docs.carto.com/analytics-toolbox-postgres/overview/getting-started/) enables our users to build high performance data visualizations from very large datasets. Check out [this example](https://docs.carto.com/analytics-toolbox-postgres/examples/creating-spatial-index-tilesets/) to learn more about how to use this feature.

{% endupdate %} {% update date="2022-07-12" tags="new,developer-tools" %} ## CARTO for React 1.3 We are excited to announce a new release of our CARTO for React library, packed with awesome new features to extend the CARTO platform and provide more capabilities for building custom solutions: * We have added support for [spatial indexes](https://docs.carto.com/react/guides/data-sources#spatial-indexes), so now you can visualize layers and add widgets when you are working with datasets using H3 and Quadbin indexes, in addition to traditional geometries. This is specially useful when you are dealing with large datasets. * We have support now for dynamic tiling. By default the CartoLayer will work with [dynamic tiles](https://docs.carto.com/react/guides/upgrade-guide/) and the widgets have been updated to work with them. * Widgets now have two different [modes](https://docs.carto.com/react/guides/widgets#modes-behavior): viewport and global. * The [GeocoderWidget](https://docs.carto.com/react/library-reference/widgets#geocoderwidget) now is compatible with the new [LDS API](/carto-for-developers/reference/carto-api). * We have a new [BarWidget](https://docs.carto.com/react/library-reference/widgets#barwidget) to display categorical/qualitative data using vertical bars. {% endupdate %} {% update date="2022-07-08" tags="new,workspace" %} ## Sharing maps and connections with groups You can now synchronize the user groups coming from your Single Sign-On (SSO) directory (e.g. SAML, LDAP, etc.) with CARTO. Thanks to this new feature users can now share maps and connections with those inherited groups. You can access full details in our documentation on [sharing with groups](https://docs.carto.com/carto-user-manual/maps/publishing-and-sharing-maps/#sharing-with-certain-groups) and [group management](https://docs.carto.com/carto-user-manual/settings/managing-user-groups/).

{% endupdate %} {% update date="2022-07-07" tags="new,builder" %} ## Custom Pop-ups in Builder maps We have released a new feature for [pop-up windows](/carto-user-manual/maps/interactions) in Builder maps. Now users can customize their pop-ups using HTML and a templating system that allows accessing feature’s properties. This kind of flexibility allows users to add dynamic content to their maps, such as: Google Street View images, custom links based on data properties, images, logos, GIFs, etc. Check out this [blogpost](https://carto.com/blog/google-street-view-pop-ups-with-carto/) to see some examples of this feature in action. {% embed url="" %} {% endupdate %} {% update date="2022-07-01" tags="new,developer-tools" %} ## CARTO for deck.gl 8.8 We are really happy to announce a new release of “CARTO for deck.gl” to allow developers to build even more awesome apps and map visualizations with the CARTO platform. This new release comes from: * Support in the CartoLayer for datasets using spatial indexes such as H3 and Quadbin. You can now build visualizations with very large datasets without the need of geometry data at an incredible performance and reduced costs. * You can now leverage our Dynamic Tiling system with SQL Queries, providing great scaling capabilities to your maps. * deck.gl code base is now migrated to TypeScript. This improves the robustness and maintainability of TypeScript apps using deck.gl as well as the deck.gl codebase itself. {% embed url="" %} {% endupdate %} {% endupdates %} # FAQs Frequently Asked Questions about the CARTO platform and its components. ## **CARTO Accounts** * [What is the new version of the CARTO platform?](/faqs/accounts#what-is-the-new-version-of-the-carto-platform) * [Is the previous version of CARTO going to be deprecated?](/faqs/accounts#is-the-previous-version-of-carto-going-to-be-deprecated) * [How can I log into the legacy CARTO platform?](/faqs/accounts#how-can-i-log-into-the-legacy-carto-platform) * [Can I login to both versions of the CARTO platform with the same credentials?](/faqs/accounts#can-i-login-to-both-versions-of-the-carto-platform-with-the-same-credentials) * [Will all my data in the previous platform be readily available when I access the new version of CARTO?](/faqs/accounts#will-all-my-data-in-the-previous-platform-be-readily-available-when-i-access-the-new-version-of-cart) * [Will I be forced to move all my data to the new version of the CARTO platform?](/faqs/accounts#will-i-be-forced-to-move-all-my-data-to-the-new-version-of-the-carto-platform) * [Is CARTO’s Student Package still available?](/faqs/accounts#is-cartos-student-package-still-available) * [Can I setup a Single Sign-On integration in the new platform?](/faqs/accounts#can-i-setup-a-single-sign-on-integration-in-the-new-platform) * [Where can I see my current quotas and usage?](/faqs/accounts#where-can-i-see-my-current-quotas-and-usage) ## **Migration to the new platform** * [Why should I migrate to the new version of the CARTO platform?](/faqs/migration-to-the-new-platform#why-should-i-migrate-to-the-new-version-of-the-carto-platform) * [Is CARTO going to provide me assistance if I would like to migrate to the new platform?](/faqs/migration-to-the-new-platform#is-carto-going-to-provide-me-assistance-if-i-would-like-to-migrate-to-the-new-platform) * [What type of objects can be migrated between platforms?](/faqs/migration-to-the-new-platform#what-type-of-objects-can-be-migrated-between-platforms) * [Can I migrate my maps from the previous version to the new version of CARTO?](/faqs/migration-to-the-new-platform#can-i-migrate-my-maps-from-the-previous-version-to-the-new-version-of-carto) * [What information will you need to provide to receive assistance with the migration?](/faqs/migration-to-the-new-platform#what-information-will-you-need-to-provide-to-receive-assistance-with-the-migration) * [Do I need to provide an authorization for CARTO to work on my platform migration?](/faqs/migration-to-the-new-platform#do-i-need-to-provide-an-authorization-for-carto-to-work-on-my-platform-migration) * [If my data tables are migrated to the CARTO Data Warehouse in the new platform, are there any associated costs with its usage?](/faqs/migration-to-the-new-platform#if-my-data-tables-are-migrated-to-the-carto-data-warehouse-in-the-new-platform-are-there-any-associa) * [Will the platform migration tasks interfere with the standard service?](/faqs/migration-to-the-new-platform#will-the-platform-migration-tasks-interfere-with-the-standard-service) ## Users & account setup * [My screen is stuck on the "Creating an Organization" page.](/faqs/user-and-organization-setup#my-screen-is-stuck-on-the-creating-an-organization-page) * [How can I join an existing organization on CARTO?](/faqs/user-and-organization-setup#how-can-i-join-an-existing-organization-on-carto) * [Can I be a member of multiple CARTO organizations?](/faqs/user-and-organization-setup#can-i-be-a-member-of-multiple-carto-organizations) * [I have previously used CARTO (including signing up for a free trial). Can I create a new organization or user with the same email?](https://docs.carto.com/pages/YpAygBR0PIl9E5gxW7KV#i-have-previously-used-carto-including-signing-up-for-a-free-trial-.-can-i-create-a-new-organization) * [Can I extend my free trial to longer than 14 days?](/faqs/user-and-organization-setup#can-i-extend-my-free-trial-to-longer-than-14-days) * [Can I start multiple free trials with CARTO?](/faqs/user-and-organization-setup#can-i-start-multiple-free-trials-with-carto) ## **General** * [What cloud data warehouses can I use with CARTO?](/faqs/workspace#what-cloud-data-warehouses-can-i-use-with-carto) * [What are the device/web browser requirements for CARTO?](/faqs/workspace#what-are-the-device-web-browser-requirements-for-carto) * [When I connect to a data warehouse, do you copy or store any data?](/faqs/workspace#when-i-connect-to-a-data-warehouse-do-you-copy-or-store-any-data) * [What happens if I do not have any cloud data warehouse platform to connect?](/faqs/workspace#what-happens-if-i-do-not-have-any-cloud-data-warehouse-platform-to-connect) * [Can I import geospatial files into CARTO’s new platform?](/faqs/workspace#can-i-import-geospatial-files-into-cartos-new-platform) * [What are the Location Data Services (LDS) providers configured by default in a CARTO organization?](#general) ## **Builder** * [What methods can I use to create a map layer?](/faqs/builder#what-methods-can-i-use-to-create-a-map-layer) * [How can I run spatial analyses in Builder?](/faqs/builder#how-can-i-run-spatial-analyses-in-builder) * [How does the export mechanism from Builder works?](#how-does-the-export-mechanism-from-builder-works) ## Workflows * [When creating a new workflow, I cannot see the data sources available in my connection - what may be happening?](/faqs/workflows#when-creating-a-new-workflow-i-cannot-see-the-data-sources-available-in-my-connection-what-may-be-ha) * [Working with my data sources from a BigQuery connection I receive an error message about not having permissions to query the table or that the table does not exist on a specific region - What may be happening?](/faqs/workflows#working-with-my-data-sources-from-a-bigquery-connection-i-receive-an-error-message-about-not-having) * [Working with my data sources from a Snowflake connection I receive the following error message: "cannot get Workflow schema" - What may be happening?](/faqs/workflows#working-with-my-data-sources-from-a-snowflake-connection-i-receive-the-following-error-message-canno) * [My workflow is producing the error message “No value assigned.” What could be causing this?](https://docs.carto.com/pages/DZ4UBfLTuI0ccXtBWiS1#my-workflow-is-producing-the-error-message-no-value-assigned.-what-could-be-causing-this) ## **Data Observatory** * [Can I license premium data with a trial or student account?](/faqs/data-observatory#can-i-license-premium-data-with-a-trial-individual-or-student-account) * [Are premium data subscriptions based on perpetual licenses?](/faqs/data-observatory#are-premium-data-subscriptions-based-on-perpetual-licenses) * [Can I export the data from CARTO and use it on other platforms?](/faqs/data-observatory#can-i-export-the-data-from-carto-and-use-it-on-other-platforms) ## **Analytics Toolbox** * [What is CARTO’s Analytics Toolbox?](/faqs/analytics-toolbox#what-is-cartos-analytics-toolbox) * [How can I use the functions available in the Analytics Toolbox?](/faqs/analytics-toolbox#how-can-i-use-the-functions-available-in-the-analytics-toolbox) * [Can I use the Analytics Toolbox from the CARTO Data Warehouse connection?](/faqs/analytics-toolbox#can-i-use-the-analytics-toolbox-from-the-carto-data-warehouse-connection) * [In the Analytics Toolbox for BigQuery, are there differences when using it from different GCP regions?](/faqs/analytics-toolbox#in-the-analytics-toolbox-for-bigquery-are-there-differences-when-using-it-from-different-gcp-regions) ## **Development Tools** * [What frameworks and libraries can I use for developing custom apps with CARTO?](/faqs/development-tools#what-frameworks-and-libraries-can-i-use-for-developing-custom-apps-with-carto) * [Are “CARTO for deck.gl” and “CARTO for React” compatible with the new version of the platform?](https://docs.carto.com/pages/p8BaYli2tNgoTXw3XKFs#are-carto-for-deck.gl-and-carto-for-react-compatible-with-the-new-version-of-the-platform) * [Does CARTO provide an SDK for the development of Mobile applications?](/faqs/development-tools#does-carto-provide-an-sdk-for-the-development-of-mobile-applications) ## **Deployment Options** * [What are the different deployment options for the CARTO platform?](/faqs/deployment-options#what-are-the-different-deployment-options-for-the-carto-platform) * [Where can I find information about the requirements for deploying CARTO as Self-hosted?](/faqs/deployment-options#where-can-i-find-information-about-the-requirements-for-deploying-carto-as-self-hosted) * [How are updates and product releases managed in a Self-hosted deployment?](/faqs/deployment-options#how-are-updates-and-product-releases-managed-in-a-self-hosted-deployment) * [Where can I find information about deploying CARTO with Snowflake Container Services?](/faqs/deployment-options#where-can-i-find-information-about-deploying-carto-with-snowflake-container-services) ## **Support Packages** * [What support packages are available at CARTO?](/faqs/support-packages#what-support-packages-are-available-at-carto) * [Who is entitled to Support?](/faqs/support-packages#who-is-entitled-to-support) * [What are CARTO Business Hours?](/faqs/support-packages#what-are-carto-business-hours) * [What are Customer Success Managers (CSMs)?](/faqs/support-packages#what-are-customer-success-managers-csms) * [How to submit an issue to our Support team?](/faqs/support-packages#how-to-submit-an-issue-to-our-support-team) * [What is the issue and severity classification?](/faqs/support-packages#what-is-the-issue-and-severity-classification) * [What are CARTO’s Target Response Times (business hours)?](/faqs/support-packages#what-are-cartos-target-response-times-business-hours) ## **CARTO Basemaps** * [Does CARTO provide a basemap service?](/faqs/carto-basemaps#does-carto-provide-a-basemap-service) * [What is the pricing for CARTO basemaps? Is it free?](/faqs/carto-basemaps#what-is-the-pricing-for-carto-basemaps-is-it-free) * [Why do I see an "API key required" watermark?](/faqs/carto-basemaps#why-do-i-see-an-api-key-required-watermark) * [Why are my tiles refused (403) when my key has website restrictions?](/faqs/carto-basemaps#why-are-my-tiles-refused-403-when-my-key-has-website-restrictions) * [Should I move from raster to vector basemaps?](/faqs/carto-basemaps#should-i-move-from-raster-to-vector-basemaps) * [How frequently does CARTO update its basemaps?](/faqs/carto-basemaps#how-frequently-does-carto-update-its-basemaps) * [Can I use other basemaps in CARTO?](/faqs/carto-basemaps#can-i-use-other-basemaps-in-carto) * [I already use the basemaps commercially. What changes for me?](https://docs.carto.com/pages/sbh5qlPtgGk67Ao2HxSD#i-already-use-the-basemaps-commercially.-what-changes-for-me) * [I am a CARTO customer. Do I need to buy anything?](https://docs.carto.com/pages/sbh5qlPtgGk67Ao2HxSD#i-am-a-carto-customer.-do-i-need-to-buy-anything) ## **CARTO for Education** * [How can I get a Student account in CARTO?](/faqs/carto-for-education#how-can-i-get-a-student-account-in-carto) * [How can I get an Educator account?](/faqs/carto-for-education#how-can-i-get-an-educator-account) * [We need Enterprise capabilities for our institution or academic research, can you help?](/faqs/carto-for-education#we-need-enterprise-capabilities-for-our-institution-or-academic-research-can-you-help) * [What is the process for getting a CARTO Student account?](/faqs/carto-for-education#what-is-the-process-for-getting-a-carto-student-account) * [I am an educator and my course materials use the previous version of CARTO. What can I do?](https://docs.carto.com/pages/l5e2QX8UeoNbf9fcV8sV#i-am-an-educator-and-my-course-materials-use-the-previous-version-of-carto.-what-can-i-do) ## Security and Compliance * [Is the CARTO Platform SOC 2 Type II-certified?](/faqs/security-and-compliance#is-the-carto-platform-soc-2-type-ii-certified) * [Does it comply with GDPR, CCPA and other data privacy laws?](/faqs/security-and-compliance#does-it-comply-with-gdpr-ccpa-and-other-data-privacy-laws) * [What are the password and login management controls in CARTO?](/faqs/security-and-compliance#what-are-the-password-and-login-management-controls-in-carto) * [When we create a connection to CARTO, does it make any copies of our data?](/faqs/security-and-compliance#when-we-create-a-connection-to-carto-does-it-make-any-copies-of-our-data) * [How does CARTO manage user data?](/faqs/security-and-compliance#how-does-carto-manage-user-data) * [Where is my data stored?](/faqs/security-and-compliance#where-is-my-data-stored) * [How does CARTO manage security when a map, a workflow or an application are shared?](/faqs/security-and-compliance#how-does-carto-manage-security-when-a-map-workflow-or-an-application-are-shared) # Accounts [What is the new version of the CARTO platform?](#what-is-the-new-version-of-the-carto-platform) [Is the previous version of CARTO going to be deprecated?](#is-the-previous-version-of-carto-going-to-be-deprecated) [How can I log into the legacy CARTO platform?](#how-can-i-log-into-the-legacy-carto-platform) [What happens to my current CARTO subscription? Will I have to pay extra to access the new platform?](#what-happens-to-my-current-carto-subscription-will-i-have-to-pay-extra-to-access-the-new-platform) [Can I login to both versions of the CARTO platform with the same credentials?](#can-i-login-to-both-versions-of-the-carto-platform-with-the-same-credentials) [Will all my data in the previous platform be readily available when I access the new version of CARTO?](#will-all-my-data-in-the-previous-platform-be-readily-available-when-i-access-the-new-version-of-cart) [Will I be forced to move all my data to the new version of the CARTO platform?](#will-i-be-forced-to-move-all-my-data-to-the-new-version-of-the-carto-platform) [Is CARTO’s Student Package still available?](#is-cartos-student-package-still-available) [Can I setup a Single Sign-On integration in the new platform?](#can-i-setup-a-single-sign-on-integration-in-the-new-platform) [Where can I see my current quotas and usage?](#where-can-i-see-my-current-quotas-and-usage) *** #### **What is the new version of the CARTO Platform?** In October 2021, we launched a fully revamped version of the [CARTO platform](http://www.carto.com/carto3/). The new platform offers a complete cloud native experience, allowing to run CARTO on top of the leading cloud data warehouse platforms (e.g. Google BigQuery, AWS Redshift, Snowflake, Databricks, Oracle, etc.), eliminating ETL complexity and limits on scalability. This new platform works completely independent of the previous version of CARTO; hence, requires a different set of user credentials to access. You can learn more about the new platform with our [User Manual](https://docs.carto.com/carto-user-manual/overview/getting-started/#getting-started). *** #### **Is the previous version of CARTO going to be deprecated?** No, we don’t have plans to deprecate the previous version of our platform for our existing Enterprise customers, so you don’t need to worry about that now. However, it is important to note that any new product developments will happen only in the new version of CARTO. You can continue to login to the previous version of CARTO from [this page](https://carto.com/login). Free trials for the new CARTO platform are already available on our [Sign up page](http://www.carto.com/signup). We also welcome all of our existing enterprise customers to contact us so we can provision them an account to the new platform for the reminder of their subscription term. *** #### **How can I log into the legacy CARTO platform?** Although direct login to the legacy platform was removed from CARTO's website homepage in February 2024, you can continue to log into your account in the previous version of CARTO from [this page](https://carto.com/login). *** #### **What happens to my current CARTO subscription? Will I have to pay extra to access the new platform?** If you are an existing CARTO Enterprise customer, we will give you an account to the new version of our platform without any additional cost for the reminder of your subscription term. Please get in touch with your CARTO representative or our Support team and we will provision you an enterprise account to the new platform according to your subscription plan. *** #### **Can I login to both versions of the CARTO platform with the same credentials?** No, the two platforms are completely independent, and hence they require their own set of credentials to login. In our login page users can select which version of CARTO they want to access. To access your old account, select “CARTO Dashboard”. *** #### **Will all my data in the previous platform be readily available when I access the new version of CARTO?** No, by default it is not. Both versions of the platform are completely independent. Get in touch with your CARTO representative or our Support team, and we can assist you to migrate your datasets across our two platform versions. *** #### **Will I be forced to move all my data to the new version of the CARTO platform?** No, you won’t. If you are an existing CARTO customer you can enjoy both versions of the platform. If you are an existing enterprise customer, and you would like to make available in the new platform some of the tables you have in your existing account, please get in touch with your CARTO representative or our Support team, and we can assist you to migrate data across our two platform versions. *** #### **Is CARTO’s Student Package still available?** Yes, it is. Check [our guide here](https://docs.carto.com/faqs/categories/carto-for-education/) and learn how to activate your CARTO Student account using the Github Student Developer Pack. *** #### **Can I setup a Single Sign-On integration in the new platform?** Yes, check all the details in [our SSO documentation](/carto-user-manual/settings/sso). To get started, just get in touch with your contact or with and we’ll guide you through the process. In the end, users in your organization will see your SSO integration as the only way to access your organization. *** #### **Where can I see my current quotas and usage?** To understand the current plan limits (quotas) and how far are you from reaching them, there’s a section located in Workspace > Settings > Subscription > Quotas where you can check all this information at any time. Check [Understanding your Organization Quotas](/carto-user-manual/settings/quotas-and-rate-limits/understanding-your-organization-quotas) for examples and more information. # Migration to the new platform [Why should I migrate to the new version of the CARTO platform?](https://docs.carto.com/faqs/categories/migration-to-the-new-platform/#why-should-i-migrate-to-the-new-version-of-the-carto-platform) [Is CARTO going to provide me assistance if I would like to migrate to the new platform?](https://docs.carto.com/faqs/categories/migration-to-the-new-platform/#is-carto-going-to-provide-me-assistance-if-i-would-like-to-migrate-to-the-new-platform) [What type of objects can be migrated between platforms?](https://docs.carto.com/faqs/categories/migration-to-the-new-platform/#what-type-of-objects-can-be-migrated-between-platforms) [Can I migrate my maps from the previous version to the new version of CARTO?](https://docs.carto.com/faqs/categories/migration-to-the-new-platform/#can-i-migrate-my-maps-from-the-previous-version-to-the-new-version-of-carto) [What information will you need to provide to receive assistance with the migration?](https://docs.carto.com/faqs/categories/migration-to-the-new-platform/#what-information-will-you-need-to-provide-to-receive-assistance-with-the-migration) [Do I need to provide an authorization for CARTO to work on my platform migration?](https://docs.carto.com/faqs/categories/migration-to-the-new-platform/#do-i-need-to-provide-an-authorization-for-carto-to-work-on-my-platform-migration) [If my data tables are migrated to the CARTO Data Warehouse in the new platform, are there any associated costs with its usage?](https://docs.carto.com/faqs/categories/migration-to-the-new-platform/#if-my-data-tables-are-migrated-to-the-carto-data-warehouse-in-the-new-platform-are-there-any-associated-costs-with-its-usage) [Will the platform migration tasks interfere with the standard service?](https://docs.carto.com/faqs/categories/migration-to-the-new-platform/#will-the-platform-migration-tasks-interfere-with-the-standard-service) *** #### **Why should I migrate to the new version of the CARTO platform?** The new platform offers you a complete cloud native experience, and unparalleled geospatial analysis and visualization capabilities on top of the leading cloud data warehouse platforms (i.e. Google BigQuery, Snowflake, AWS Redshift, Oracle and Databricks), eliminating the need of complex ETLs and the limits of scalability that our previous platform had. In the new CARTO, we have implemented a new and more powerful version of CARTO Builder, further advanced our Data Observatory and Development tools, and created a new suite of geospatial analytics functions that can be run natively in the aforementioned cloud data warehouse platforms. Our teams are currently laser focused on evolving both functionality and user experience to make the new CARTO the most powerful spatial analytics platform available in the market. Although we currently do not have any plans to deprecate the previous version, **we recommend you to start your new projects in the new CARTO platform**. CARTO will not be doing any further developments on the components of the old version of the platform, which will remain “as is”. *** #### **Is CARTO going to provide me assistance if I would like to migrate to the new platform?** CARTO offers technical assistance for platform migrations to all our enterprise customers at no additional cost. If you have an Enterprise plan and you would like our assistance to migrate to the new version of our platform, please contact your CARTO representative or the Support team at . *** #### **What type of objects can be migrated between platforms?** We can only offer migration support between platform versions for data tables and your active Data Observatory subscriptions. *** #### **Can I migrate my maps from the previous version to the new version of CARTO?** No. Unfortunately, since the technology stack between platforms is completely different, we cannot offer compatibility of maps built in the previous version of CARTO with our new technology. If you have TAM hours in your Support package, please ask your Customer Success Manager for an evaluation of the effort required to build your maps in the new platform. *** #### **What information will you need to provide to receive assistance with the migration?** In order for us to assist you with the migration to the new CARTO platform, we will need to receive the following information about your CARTO account in the previous version of the platform: * The name(s) of the CARTO organization(s) in the previous version of the platform that you want to migrate to the new version; * The name of the CARTO organization in the new platform to which you want to migrate your data to; * A list of the data tables to migrate; * An estimate on the size of the tables that you want to migrate; * Whether you have a cloud data warehouse from the supported ones (i.e. Google BigQuery, AWS Redshift, Snowflake, Databricks, Oracle) or your own PostgreSQL database to which you want to migrate the data to use it with the new platform. If not, we will migrate your data to your instance in the [CARTO Data Warehouse](https://docs.carto.com/carto-user-manual/connections/carto-data-warehouse/). *** #### **Do I need to provide an authorization for CARTO to work on my platform migration?** Yes. For us to be able to actively assist you with the platform migration, we will need you to send us a written authorization with the following text in order to give us the required permissions: {% hint style="info" %} **Authorization** “I request CARTO to create an additional Editor user in my CARTO organization account on the new platform version. This Editor user will be only used by the CARTO team to migrate my data from the previous version of CARTO to the new platform (“Migration Services”). I also grant CARTO access to my organization account {NAME OF THE ACCOUNT} in the previous platform version of CARTO as part of the Migration Services. Once the Migration Services are completed, CARTO will hand over the tables created and will remove the additional Editor user created in my CARTO organization account. CARTO’s team will only have access to the data in my CARTO accounts in order to perform the Migration Services.” {% endhint %} #### **If my data tables are migrated to the CARTO Data Warehouse in the new platform, are there any associated costs with its usage?** CARTO provides an instance of the CARTO Data Warehouse and monthly usage quotas with every subscription plan depending on the tier. Please get in touch with your CARTO representative to understand the service level associated with your subscription plan. You can read more information on this topic [here](https://docs.carto.com/carto-user-manual/connections/carto-data-warehouse/). *** #### **Will the platform migration tasks interfere with the standard service?** Any task associated with the platform migration is not expected to interfere with your CARTO service. In any case, CARTO will agree with you on a timeframe to carry out the migration activities, so you are completely informed on when these will be performed and therefore reduce the chances of any interference with your own usage of your CARTO accounts. # User & organization setup [My screen is stuck on the "Creating an Organization" page.](#my-screen-is-stuck-on-the-creating-an-organization-page) [How can I join an existing organization on CARTO?](#how-can-i-join-an-existing-organization-on-carto) [Can I be a member of multiple CARTO organizations?](#can-i-be-a-member-of-multiple-carto-organizations) [I have previously used CARTO (including signing up for a free trial). Can I create a new organization or user with the same email?](#i-have-previously-used-carto-including-signing-up-for-a-free-trial-.-can-i-create-a-new-organization) [Can I extend my free trial to longer than 14 days?](#can-i-extend-my-free-trial-to-longer-than-14-days) [Can I start multiple free trials with CARTO?](#can-i-start-multiple-free-trials-with-carto) *** ### My screen is stuck on the "Creating an Organization" page. If you have never signed up for CARTO before, this can normally be fixed by clearing your browser’s cache. If you have previously used CARTO or created another CARTO organization - including a free trial - please see the FAQs below. *** ### How can I join an existing organization on CARTO? A CARTO user with an admin role from your organization will be able to add you to their organization through the CARTO Workspace via Settings > Users and Groups. If you have a previous or existing CARTO login (including free trials) which are not attached to this organization, you will not be able to immediately join. In this instance, you should contact your customer success manager or who can help you. *** ### Can I be a member of multiple CARTO organizations? You cannot join multiple CARTO organizations with the same email address. If you have a requirement like this, you should contact your customer success manager or who can help you. *** ### I have previously used CARTO (including signing up for a free trial). Can I create a new organization or user with the same email? CARTO accounts are currently limited to one account per email, including historic accounts. If you have specific requirements around this, please contact your customer success manager or who can help you. If you are attending a CARTO event where a free trial is a requirement, please contact the event organizers who will be able to coordinate this for you. *** ### Can I extend my free trial to longer than 14 days? In most cases free trials are limited to 14 days. Please fill in our [Request a demo](https://carto.com/request-live-demo) form to discuss your requirements if you weren’t able to evaluate the platform within 14 days. *** ### Can I start multiple free trials with CARTO? Free trials are limited to one per user. Please fill in our [Request a demo](https://carto.com/request-live-demo) form to discuss your requirements if you weren’t able to evaluate the platform with a single trial. If you are attending a CARTO event where a free trial is a requirement, please contact the event organizers who will be able to coordinate this for you. # General [What cloud data warehouses can I use with CARTO?](#what-cloud-data-warehouses-can-i-use-with-carto) [What are the device/web browser requirements for CARTO?](#what-are-the-device-web-browser-requirements-for-carto) [When I connect to a data warehouse, do you copy or store any data?](#when-i-connect-to-a-data-warehouse-do-you-copy-or-store-any-data) [What happens if I do not have any cloud data warehouse platform to connect?](#what-happens-if-i-do-not-have-any-cloud-data-warehouse-platform-to-connect) [Can I import geospatial files into CARTO’s new platform?](#can-i-import-geospatial-files-into-cartos-new-platform) [What are the Location Data Services (LDS) providers configured by default in a CARTO organization?](#what-are-the-location-data-services-lds-providers-configured-by-default-in-a-carto-organization) *** #### **What cloud data warehouses can I use with CARTO?** CARTO's new platform is designed to give you a fully cloud native experience, allowing you to run CARTO on top of your leading cloud data warehouse platform of choice (i.e. Google BigQuery, Snowflake, AWS Redshift, Oracle, Databricks, and any PostgreSQL-based data warehouse platform). *** #### **What are the device/web browser requirements for CARTO?** CARTO is designed to work in all modern browsers that meet the following criteria: * Complete support, including hardware acceleration, for [WebGL2](https://get.webgl.org/) * A browser version not older than 2 years This includes the latest stable versions of Google Chrome, Safari, Firefox, Microsoft Edge, and Opera, but other browsers using standard technology and meeting the criteria above should be compatible as well. While CARTO should work in all browsers meeting the criteria above, the best performance and compatibility are expected with Chromium-based browsers. Please note that the user's device must also have hardware that supports these features. A desktop device with a dedicated GPU and at least 8 GB of RAM is recommended. *** #### **When I connect to a data warehouse, do you copy or store any data?** No, your connection allow us to perform queries against your data on your behalf, and the results are either stored again in your data warehouse or rendered in the client, as visible maps. CARTO being fully cloud native means no storage needs, less security concerns and no need for data replication or complex ETL processing. *** #### **What happens if I do not have any cloud data warehouse platform to connect?** For users who do not have any cloud data warehouse platform to which they want to connect CARTO, we are offering cloud storage and computing resources in what we call the CARTO Data Warehouse. A CARTO Data Warehouse connection is offered by default with your CARTO subscription. *** #### **Can I import geospatial files into CARTO’s new platform?** Yes. You can import both local and remote (via URL) files. CARTO supports importing **CSV**, **GeoJSON**, **GeoPackage**, **KML**, **KMZ**, **TAB**, **Shapefiles** (in a `.zip` package), and [**GeoParquet**](https://geoparquet.org/) files. These formats can be imported into any connected data warehouse. **GeoTIFF** raster files are also supported when importing into **BigQuery**, **Snowflake**, and **Databricks** connections. The resulting table follows the [**Raquet**](https://github.com/CartoDB/raquet) specification. The size limit for file imports is **5 GB** for all formats. You'll find more details in the [Importing data](https://docs.carto.com/carto-user-manual/data-explorer/importing-data/) section of our User Manual. *** #### **What are the Location Data Services (LDS) providers configured by default in a CARTO organization?** CARTO offers access to Location Data Services (LDS) such as geocoding, isolines and routing by leveraging the APIs of 3rd party service providers. Since December 2023, by default, CARTO uses [TomTom](https://developer.tomtom.com/documentation) APIs for geocoding and routing, and [TravelTime](https://docs.traveltime.com/api/overview/introduction) for isolines. CARTO retains the right to adjust the default configuration of these services at its sole discretion when deemed necessary. Other options to the default can be made available under special commercial and usage terms. # Builder [What methods can I use to create a map layer?](https://docs.carto.com/faqs/categories/builder/#what-methods-can-i-use-to-create-a-map-layer) [How can I run spatial analyses in Builder?](https://docs.carto.com/faqs/categories/builder/#how-can-i-run-spatial-analyses-in-builder) [How does the export mechanism from Builder works?](#how-does-the-export-mechanism-from-builder-works) *** #### **What methods can I use to create a map layer?** To add a data source to a map as a new layer you can either: * Pick a table or tileset from one of your active connections to cloud data warehouses * Add data resulting from applying a custom SQL Query. You can also leverage the SQL functions available in CARTO’s [Analytics Toolbox](https://docs.carto.com/carto-user-manual/maps/add-source/#custom-queries-using-the-analytics-toolbox). * Importing data from a local or remote file. See the [supported import formats](https://docs.carto.com/carto-user-manual/data-explorer/importing-data/#supported-formats) for the full list. *** #### **How can I run spatial analyses in Builder?** To run spatial analysis in Builder, you can use the SQL Editor, which is accessible when adding a data source as a custom query. The SQL Editor allows you to execute SQL commands directly in your cloud data warehouse (e.g., BigQuery, Snowflake, etc.), taking advantage of the full capabilities of the platform, including functions and operations available there. Additionally, you can leverage UDFs from the Analytics Toolbxo for enhanced spatial analysis.\ \ While the SQL Editor is ideal for performing simple analysis or utilizing SQL Parameters, for more complex or multi-step analysis, we recommend using Workflows. Workflows enable you to perform detailed, step-by-step analysis and save the results as a materialized table, which can then be used as a source in Builder. This approach provides greater flexibility and scalability for more advanced spatial analysis tasks. *** #### How does the export mechanism from Builder works? The export mechanism in Builder leverages the built-in export functionality of the connected cloud data warehouse to handle and process data. This ensures efficient export of datasets, aligning with the performance optimization strategies of the underlying platform. When using BigQuery specifically, the export process stores data in a Google Cloud Storage (GCS) bucket. For performance and scalability, BigQuery splits the exported data into multiple smaller files rather than a single large file. This behavior is expected and is a result of BigQuery's internal strategies to parallelize the export jobs for optimal performance. *** #### Does Builder support GEOMETRYCOLLECTION geometry type? No, Builder does not support GEOMETRYCOLLECTION geometry types. If your data contains geometry collections, you'll need to convert them to individual geometry components (Point, LineString, or Polygon) using SQL transformations before visualization. See the [Simple Features documentation](/carto-user-manual/maps/data-sources/simple-features) for workaround examples using ST\_Dump. \ \\ # Workflows [When creating a new workflow, I cannot see the data sources available in my connection - what may be happening?](#when-creating-a-new-workflow-i-cannot-see-the-data-sources-available-in-my-connection-what-may-be-ha) [Working with my data sources from a BigQuery connection I receive an error message about not having permissions to query the table or that the table does not exist on a specific region - What may be happening?](#working-with-my-data-sources-from-a-bigquery-connection-i-receive-an-error-message-about-not-having) [Working with my data sources from a Snowflake connection I receive the following error message: "cannot get Workflow schema" - What may be happening?](#working-with-my-data-sources-from-a-snowflake-connection-i-receive-the-following-error-message-canno) [My workflow is producing the error message “No value assigned.” What could be causing this?](#my-workflow-is-producing-the-error-message-no-value-assigned.-what-could-be-causing-this) #### When creating a new workflow, I cannot see the data sources available in my connection - what may be happening? This may be because the data warehouse connection associated with the workflow does not have the required permissions to run Workflows in the data warehouse, such as the permission of creating schemas in the Workflows temp. location (configured in the advanced options of the connection card). Please choose or create another connection with data owner permissions or modify the permissions in the current connection and try again. If the issue persists, please contact our support team at . #### Working with my data sources from a BigQuery connection I receive an error message about not having permissions to query the table or that the table does not exist on a specific region - What may be happening? In order to function, CARTO Workflows creates a temporal dataset in BigQuery named `workflows_temp` in where to store temporary objects needed to fully execute a workflow. In BigQuery, we create such dataset in the default region of the GCP project associated to the [BigQuery connection](https://docs.carto.com/carto-user-manual/connections/creating-a-connection#connection-to-bigquery). If you then want to include in a workflow data sources that are stored in another region different to the "default" one of your GCP project, then you need to create a new `workflows_temp` dataset in that other region and specify its location in the Advanced options of your BigQuery connection.

#### Working with my data sources from a Snowflake connection I receive the following error message: "cannot get Workflow schema" - What may be happening? In order to guarantee a successful execution of a workflow via a Snowflake connection, please make sure that in the settings of the [connection](/carto-user-manual/connections) you have specified the database of your Snowflake account with which you want to work via that specific connection. This field is now required by CARTO Workflows. Note that you can [edit](https://github.com/CartoDB/gitbook-documentation/blob/master/faqs/broken-reference/README.md) an existing connection at any time. #### My workflow is producing the error message "no value assigned." What could be causing this? Usually this error occurs when either the input data sources have not finished loading, or the workflow has not had time to fully initialize before you’ve run it. This means that your later components have not had a chance to work out which values it will be receiving from the previous components. This can usually be fixed by re-running the workflow. # Data Observatory [Can I license premium data with a trial or student account?](https://docs.carto.com/faqs/categories/data-observatory/#can-i-license-premium-data-with-a-trial-individual-or-student-account) [Are premium data subscriptions based on perpetual licenses?](https://docs.carto.com/faqs/categories/data-observatory/#are-premium-data-subscriptions-based-on-perpetual-licenses) [Can I export the data from CARTO and use it on other platforms?](https://docs.carto.com/faqs/categories/data-observatory/#can-i-export-the-data-from-carto-and-use-it-on-other-platforms) *** #### **Can I license premium data with a trial, or student account?** No, premium data subscriptions are only available for Enterprise plans. For Trial and Student plans, you will only have access to data samples or public data products from the Data Observatory. Individual plans do not get access to the Data Observatory. If you need to use it, you would need to upgrade to a Starter plan, or get in touch with *** #### **Are premium data subscriptions based on perpetual licenses?** Premium subscriptions are offered on a Data-as-a-Service model based on yearly or multi-yearly licenses. Once the subscription expires and it is not renewed, the user needs to stop using and delete the associated datasets from the account. *** #### **Can I export the data from CARTO and use it on other platforms?** It will depend on the data provider and the type of license you have purchased for your premium data subscription. Some data providers offer different types of licenses if their data is going to be used only within a CARTO application or exported into other technologies. # Analytics Toolbox [What is CARTO’s Analytics Toolbox?](https://docs.carto.com/faqs/categories/analytics-toolbox/#what-is-cartos-analytics-toolbox) [How can I use the functions available in the Analytics Toolbox?](https://docs.carto.com/faqs/categories/analytics-toolbox/#how-can-i-use-the-functions-available-in-the-analytics-toolbox) [Can I use the Analytics Toolbox from the CARTO Data Warehouse connection?](https://docs.carto.com/faqs/categories/analytics-toolbox/#can-i-use-the-analytics-toolbox-from-the-carto-data-warehouse-connection) [In the Analytics Toolbox for BigQuery, are there differences when using it from different GCP regions?](https://docs.carto.com/faqs/categories/analytics-toolbox/#in-the-analytics-toolbox-for-bigquery-are-there-differences-when-using-it-from-different-gcp-regions) *** #### **What is CARTO’s Analytics Toolbox?** CARTO’s Analytics Toolbox is a set of UDFs and Store Procedures to unlock Spatial Analytics directly on top of your cloud data warehouse platform. It is organized in a set of modules based on the functionality they offer. *** #### **How can I use the functions available in the Analytics Toolbox?** You can use the functions in the Analytics Toolbox via CARTO Builder, SQL Notebooks, and directly in the console of your cloud data warehouse platform. To learn how to get access to the toolbox please visit the Documentation page for the: * [Analytics Toolbox for BigQuery](/data-and-analysis/analytics-toolbox-for-bigquery) (also valid for the CARTO Data Warehouse) * [Analytics Toolbox for Snowflake](/data-and-analysis/analytics-toolbox-for-snowflake) * [Analytics Toolbox for Redshift](/data-and-analysis/analytics-toolbox-for-redshift) * [Analytics Toolbox for Databricks](/data-and-analysis/analytics-toolbox-for-databricks) In CARTO Builder, you can use the Analytics Toolbox functions in your custom SQL queries when [adding a source](https://docs.carto.com/carto-user-manual/maps/add-source/#custom-queries-using-the-analytics-toolbox) to your map. *** #### **Can I use the Analytics Toolbox from the CARTO Data Warehouse connection?** Yes, you can. CARTO Data Warehouse connection works under the hood as a connection to Google BigQuery in the same region in which you have provisioned your CARTO organization account. Follow the same guides and reference for the [Analytics Toolbox for BigQuery](https://docs.carto.com/analytics-toolbox-bigquery/overview/getting-access/) to use this functionality from your CARTO Data Warehouse connection. *** #### **In the Analytics Toolbox for BigQuery, are there differences when using it from different GCP regions?** Yes, there are. The projects in which we install the Analytics Toolbox functions vary depending on the [cloud region](https://cloud.google.com/compute/docs/regions-zones). In this [section of the documentation](https://docs.carto.com/analytics-toolbox-bigquery/overview/regions-table/) you can find the BigQuery Project name for the Analytics Toolbox depending on the cloud region to which you have created a connection between CARTO and BigQuery. For BigQuery connections in US and EU regions, we recommend to use the Analytics Toolbox we have enabled in US multi-region (project name: carto-un) and EU multi-region (project name: carto-un-eu) Note that this also applies if you want to leverage the Analytics Toolbox from your CARTO Data Warehouse connection. # Development Tools [What frameworks and libraries can I use for developing custom apps with CARTO?](https://docs.carto.com/faqs/categories/development-tools/#what-frameworks-and-libraries-can-i-use-for-developing-custom-apps-with-carto) [Are “CARTO for deck.gl” and “CARTO for React” compatible with the new version of the platform?](https://docs.carto.com/faqs/categories/development-tools/#are-carto-for-deckgl-and-carto-for-react-compatible-with-the-new-version-of-the-platform) [How do I connect an AI agent (Claude, ChatGPT, Gemini, Copilot) to CARTO?](https://docs.carto.com/faqs/categories/development-tools/#how-do-i-connect-an-ai-agent-claude-chatgpt-gemini-copilot-to-carto) *** #### **What frameworks and libraries can I use for developing custom apps with CARTO?** You can use any framework or visualization library because CARTO is based on industry-standards. If there is not a hard requirement, we recommend using deck.gl for visualization and CARTO for React for creating apps that extend the platform functionality. *** #### **Are “CARTO for deck.gl” and “CARTO for React” compatible with the new version of the platform?** Yes, you can use both tools with the previous and the new version of the platform. *** #### **How do I connect an AI agent (Claude, ChatGPT, Gemini, Copilot) to CARTO?** Use [**CARTO for Agents**](/carto-for-agents/carto-for-agents). The [CARTO MCP Server](/carto-for-agents/mcp-server) plugs CARTO into any MCP-compatible AI client over a single URL — connect it and your agent can explore your data, create and edit Builder maps, run Workflows, and more in natural language. See [Connect your platform](/carto-for-agents/connect-your-platform) for step-by-step setup on Claude, ChatGPT, Gemini, Microsoft Copilot, Snowflake, Databricks, and others, or the [CARTO for Agents quickstart](/getting-started/quickstart-guides/connecting-carto-to-your-agents) to build your first map from a prompt. Coding agents can also use [CARTO Agent Skills](/carto-for-agents/agent-skills) and the [CARTO CLI](/carto-for-agents/cli). *** #### **Does CARTO provide an SDK for the development of Mobile applications?** CARTO does not currently offer an SDK for the development of mobile apps as a component of our cloud native platform. In order to develop mobile applications with geospatial data, we recommend using the relevant SDK of your cloud vendor, or from products such as Google Maps, Apple Maps, Mapbox or Maplibre. Particularly for the visualization of small datasets with spatial data (< 30MB), all SDKs will support visualization of GeoJSON files (e.g. [Google’s Maps SDK for Android](https://developers.google.com/maps/documentation/android-sdk/utility/geojson)), and CARTO’s [Maps API](/carto-for-developers/reference/carto-api) can be the technology to serve them. The Mobile SDK in the previous version of the CARTO platform will not be further developed, and we don’t recommend starting new projects with it. # Deployment Options [What are the different deployment options for the CARTO platform?](https://docs.carto.com/faqs/categories/deployment-options/#what-are-the-different-deployment-options-for-the-CARTO-platform) [Where can I find information about the requirements for deploying CARTO as Self-hosted?](https://docs.carto.com/faqs/categories/deployment-options/#where-can-i-find-information-about-the-requirements-for-deploying-CARTO-as-self-hosted) [How are updates and product releases managed in a Self-hosted deployment?](https://docs.carto.com/faqs/categories/deployment-options/#how-are-updates-and-product-releases-managed-in-a-self-hosted-deployment) [Where can I find information about deploying CARTO with Snowflake Container Services?](#where-can-i-find-information-about-deploying-carto-with-snowflake-container-services) *** #### **What are the different deployment options for the CARTO platform?** There are two different deployment options for the CARTO platform: * **CARTO Cloud**: A fully managed SaaS deployment that CARTO hosts on our own cloud. When you use CARTO in our cloud, we manage configuration, updates, and versioning. This option is available in different regions that you can select when [creating your organization](https://docs.carto.com/carto-user-manual/overview/getting-started/#create-a-new-organization). * **Self-Hosted**: With this option, you host your own CARTO tenant. That means it can be deployed in your virtual private cloud (VPC) or behind your virtual private network (VPN). * **(BETA) Snowflake Container Services:** Fully deploy CARTO inside Snowflake by leveraging Snowflake Native Apps and Container Services. #### **Where can I find information about the requirements for deploying CARTO as Self-hosted?** Find links to the documentation and technical requirements [here](https://github.com/CartoDB/gitbook-documentation/blob/master/faqs/broken-reference/README.md). #### **How are updates and product releases managed in a Self-hosted deployment?** While in CARTO Cloud updates and product releases are continously added to the platform, if you’re self-hosting your own CARTO tenant, it will need to be updated periodically to enjoy the latest version of the platform. The CARTO team publishes versioned releases on the public Self-hosted repositories that can be used to upgrade your deployment. Find the latest releases for [Docker](https://github.com/CartoDB/carto-selfhosted/releases/latest) and [Kubernetes](https://github.com/CartoDB/carto-selfhosted-helm/releases/latest) #### **Where can I find information about deploying CARTO with Snowflake Container Services?** Find links to the documentation [here](https://github.com/CartoDB/gitbook-documentation/blob/master/faqs/broken-reference/README.md). # CARTO Basemaps [Does CARTO provide a basemap service?](#does-carto-provide-a-basemap-service) [What is the pricing for CARTO basemaps? Is it free?](#what-is-the-pricing-for-carto-basemaps-is-it-free) [Why do I see an "API key required" watermark?](#why-do-i-see-an-api-key-required-watermark) [Why are my tiles refused (403) when my key has website restrictions?](#why-are-my-tiles-refused-403-when-my-key-has-website-restrictions) [Should I move from raster to vector basemaps?](#should-i-move-from-raster-to-vector-basemaps) [How frequently does CARTO update its basemaps?](#how-frequently-does-carto-update-its-basemaps) [Can I use other basemaps in CARTO?](#can-i-use-other-basemaps-in-carto) [I already use the basemaps commercially. What changes for me?](#i-already-use-the-basemaps-commercially.-what-changes-for-me) [I am a CARTO customer. Do I need to buy anything?](#i-am-a-carto-customer.-do-i-need-to-buy-anything) *** ### **Does CARTO provide a basemap service?** Yes. We provide a basemap service using vector tiles, and we make them automatically available in all the components in the CARTO platform (Builder, Workflows, etc...), for all users. We also serve a set of **raster (PNG) basemaps** at `basemaps.cartocdn.com`, which predate the vector service and are widely used from Leaflet and OpenLayers. They remain available and keep receiving data updates; they require an API key. Our basemaps are also compatible with Maplibre GL JS, so that [developers using deck.gl and CARTO for Developers can make use of it in their own applications](/carto-for-developers/key-concepts/carto-for-deck.gl/basemaps). The data for the CARTO basemaps is based on OpenStreetMap. Our basemaps are fully managed and powered by CARTO, including our own CDN, which makes them performant, scalable and customizable. Developers and users can choose between multiple [predefined basemap styles](https://github.com/CartoDB/basemap-styles), or even design their own styles following the *OpenMapTiles* specifications.

### **What is the pricing for CARTO basemaps? Is it free?** **There is a free tier, and how much of it you get depends on how you use the maps.** Anyone can [request an API key](https://carto.com/basemaps/apikey/); you do not need a CARTO account. The registration form asks whether your use is commercial; if that changes, write to and we update it. * **Non-commercial use** — personal, research, teaching, non-profit — is free up to **5 million tile requests per calendar month**. * **Commercial use** is free up to **1 million tile requests per calendar month**. Above that you need one of two plans, bought by card from your dashboard: **Basemaps Commercial**, $500 a month or $5,000 a year paid up front, for up to **10 million requests a month**; or **Basemaps Commercial Plus**, $1,500 a month or $15,000 a year, for up to **50 million**. Prices are plus applicable taxes; cancel any time, the paid term runs to its end. Full detail on the [basemaps page](https://carto.com/basemaps/#pricing). Requests are counted across all the keys on your account and across both the raster and vector services. Calendar months are counted in UTC. Two conditions apply to free use: * **Attribution must stay visible.** CARTO and OpenStreetMap must be credited on every map, as described in [attribution](https://carto.com/attribution/). This is what the free tier is in exchange for. * **Your key is yours.** Keys are per-customer and must not be shared or reused across unrelated projects. **Above the free allowance**, what happens depends on the use. If it is non-commercial, get in touch and we will normally raise the limit at no charge. If it is commercial, requests above 1 million a month need a Basemaps Commercial plan (Commercial to 10 million, Commercial Plus to 50 million). Already on a plan? You can move to a larger one from your dashboard. Above 50 million a month, or for anything custom, [talk to us](https://carto.com/request-live-demo/). **Basemaps are included in every CARTO plan.** CARTO customers and [CARTO grant](https://carto.com/grants/) holders do not need the Commercial plan; your limits are set by your agreement rather than by the allowances above. Full terms are in the [CARTO Basemaps Terms and Conditions](https://carto.com/legal/basemap-terms/). ### **Why do I see an "API key required" watermark?** If your map shows no streets or labels, only tiles reading **"API KEY REQUIRED · carto.com/basemaps/apikey"** on a blank background, they are being requested from our raster basemap endpoint without a usable API key. **Since 25 September 2026, raster tiles are no longer served without a key.** Until you add one, the map shows that notice instead of the basemap. (Before that date, the map stayed visible behind a watermark.) **Why we did this.** CARTO has given these basemaps away for many years, and we would like to carry on doing that. The difficulty is that without a key we cannot tell who is using the service or how much — which means we cannot warn anyone before they hit a limit, cannot tell a student project apart from a company running a product on our tiles, and cannot plan the service properly. Keys fix that, and they let us set the free tier much higher than we could when usage was anonymous. **How to fix it.** [Request an API key](https://carto.com/basemaps/apikey), then add it to your tile URL as a `key` parameter: ``` https://basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png?key=YOUR_KEY ``` A key is free (see [What is the pricing for CARTO basemaps? Is it free?](#what-is-the-pricing-for-carto-basemaps-is-it-free) for the allowances), it takes a minute, and you do not need a CARTO account. **Added a key and still see the notice?** Your browser caches tiles, so hard-refresh the page or open it in a private window. If it persists, check that the key is copied in full and exactly as issued: an incomplete key, or one with its letters changed to upper case, is treated as no key at all. **If you use basemaps inside the CARTO platform** — Builder or Workflows — this does not affect you and there is nothing to do. **Please do not try to remove or hide the notice.** Section 3.d of the [terms](https://carto.com/legal/basemap-terms/) requires that CARTO's notices and attribution stay visible, and a key is free — just ask us for one. ### **Why are my tiles refused (403) when my key has website restrictions?** A key with website restrictions only serves tiles to pages on the hosts you listed in the [Basemaps dashboard](https://dashboard.basemaps.carto.com). Every other request gets a **403**, and the map shows blank tiles. In the browser console the tile request may also appear as a CORS error. Check these, in this order — they cover almost every case we see: 1. **You are testing on your own machine** (`localhost`, `127.0.0.1`). Create a separate key for local development: it can list `localhost`, `127.0.0.1` and `*.localhost`, but a key that lists them cannot also list public sites. * Enter the host without the port. IPv6 (`[::1]`) is not supported, so use `localhost` or `127.0.0.1`. 2. **The page sends no `Referer`.** * A `Referrer-Policy: no-referrer` header or `` tag breaks every map. * `same-origin` breaks image-tile libraries (Leaflet, OpenLayers raster layers). MapLibre GL JS and Mapbox GL JS still work, because they send an `Origin`. * Native and desktop apps, `file://` pages and server-side requests send none. * The browser default is fine. * To check: open your browser's developer tools → **Network** → pick a tile request → **Request headers** → `Referer`. 3. **Hosts must match exactly.** `www.example.com` and `example.com` are different hosts, so list both. `*.example.com` covers subdomains but not `example.com` itself. Enter the host only: no `https://`, path or port. 4. **A subdomain or another site** is not in the list. 5. **Preview deployments** (Vercel, Netlify, Lovable, Cloudflare Pages…) get a new hostname on every deploy. Add a wildcard such as `*.your-project.vercel.app`, or use a separate key. 6. **Testing with `curl`** needs the header. Without it, a restricted key always returns 403: ``` curl -H 'Referer: https://yoursite.com/' '' ``` 7. **With a mobile-app restriction**, the app must send the headers shown in the dashboard: `X-Android-Package` and `X-Android-Cert`, or `X-Ios-Bundle-Identifier`. If you enable several restriction types, a request must pass all of them. Two things to know while you fix it: * **Changes you save in the dashboard apply within seconds.** Your browser may keep a refused tile for up to a minute, so hard-refresh the page. * **The "refused" counter on a key is a month-to-date total.** It will not go down after you fix things. Still stuck? Email with the tile URL and the `Referer` your browser sends. ### **Should I move from raster to vector basemaps?** **Yes, and we would recommend it regardless of the key requirement.** Our vector basemaps are better on every axis that matters: * **Sharper cartography** — crisp at any zoom level and on any display density, with no separate `@2x` request to think about. * **Restyleable at runtime.** Colours, labels and layer visibility can be changed in the browser instead of being baked into a PNG. * **Cheaper and faster to serve**, which is a large part of how we can afford to keep the free tiers generous. Both vector and raster basemaps keep receiving data updates; raster is not being retired. **Only the raster basemaps require a key today.** Vector styles still load without one. That said, **we recommend every basemap user request a key now**, whichever they use: we may extend the key requirement to vector in future, and having one already in place makes that a change you never notice rather than an interruption. Migrating means moving from a tile-URL template to a MapLibre GL JS style URL: ```javascript // Before — raster tiles in Leaflet L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png?key=YOUR_KEY', { attribution: '© OpenStreetMap, © CARTO', subdomains: 'abcd', maxZoom: 20 }).addTo(map); // After — vector style in MapLibre GL JS const map = new maplibregl.Map({ container: 'map', style: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json?key=YOUR_KEY' }); ``` | Raster style | Vector equivalent | | --------------------- | ------------------------------------------------------------------ | | `rastertiles/voyager` | `https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json` | | `light_all` | `https://basemaps.cartocdn.com/gl/positron-gl-style/style.json` | | `dark_all` | `https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json` | Attribution requirements are unchanged — see [attribution](https://carto.com/attribution/). ### **How frequently does CARTO update its basemaps?** At a minimum, CARTO updates the underlying data for its **vector** basemaps **at least once a year,** including new roads, labels, areas, and other data points. Most years we provide updates every 3 or 6 months so that data is fresh and up-to-date, but the schedule and frequency is not guaranteed. The **raster** basemaps are on the same data and keep receiving data updates. They are not being retired. ### **Can I use other basemaps in CARTO?** Yes! While customers and grantees can automatically make use of our basemaps, you can use any other basemap service of your preference: * CARTO provides out-of-the-box integration for [Google Maps basemaps in Builder](/carto-user-manual/maps/basemaps#google-maps-basemaps). * Admins can configure [additional custom basemaps ](/carto-user-manual/settings/customizations/configuring-your-organization-basemaps)that will be available for their users in Builder * Developers can integrate [any basemap provider in their CARTO + deck.gl applications](/carto-for-developers/key-concepts/carto-for-deck.gl/basemaps). ### **I already use the basemaps commercially. What changes for me?** From 23 September 2026, commercial use above 1 million tile requests a calendar month needs a Basemaps Commercial plan. If your key was registered before 23 September 2026 and you use it commercially, it keeps working as it is until **30 November 2026**. Between now and then, check your dashboard: if you serve less than 1 million requests a month, nothing changes for you. If you serve more, buy a plan from the dashboard before that date, or [talk to us](https://carto.com/request-live-demo/) if you need more than 50 million a month. ### **I am a CARTO customer. Do I need to buy anything?** No. Basemaps are included in every CARTO plan, with limits set by your agreement rather than by the free allowances above. Inside the CARTO platform — Builder and Workflows — there is nothing to set up. If you registered a basemaps key with an e-mail address for a project of your own, write to with the account ID shown on your dashboard, and we mark the account as covered. # CARTO for Education [How can I get a Student account in CARTO?](https://docs.carto.com/faqs/categories/carto-for-education/#how-can-i-get-a-student-account-in-carto) [How can I get an Educator acccount?](https://docs.carto.com/faqs/categories/carto-for-education/#how-can-i-get-an-educator-account) [We need Enterprise capabilities for our institution or academic research, can you help?](https://docs.carto.com/faqs/categories/carto-for-education/#we-need-enterprise-capabilities-for-our-institution-or-academic-research-can-you-help) [What is the process for getting a CARTO Student account?](https://docs.carto.com/faqs/categories/carto-for-education/#what-is-the-process-for-getting-a-carto-student-account) [What can I do with a CARTO Student account, and what are its limitations?](https://docs.carto.com/faqs/categories/carto-for-education/#what-can-i-do-with-a-carto-student-account-and-what-are-its-limitations) [Can I use the CARTO QGIS Plugin with my Student account?](https://docs.carto.com/faqs/categories/carto-for-education/#can-i-use-the-carto-qgis-plugin-with-my-student-account) [Can I create API Access Tokens or use CARTO programmatically?](https://docs.carto.com/faqs/categories/carto-for-education/#can-i-create-api-access-tokens-or-use-carto-programmatically) [Can I add other people to my Student account?](https://docs.carto.com/faqs/categories/carto-for-education/#can-i-add-other-people-to-my-student-account) [How long does my Student account last, and what happens when it expires?](https://docs.carto.com/faqs/categories/carto-for-education/#how-long-does-my-student-account-last-and-what-happens-when-it-expires) [I can't log in to my Student account](https://docs.carto.com/faqs/categories/carto-for-education/#i-cant-log-in-to-my-student-account) [I am an educator and my course materials use the previous version of CARTO. What can I do?](https://docs.carto.com/faqs/categories/carto-for-education/#i-am-an-educator-and-my-course-materials-use-the-previous-version-of-carto-what-can-i-do) {% hint style="info" %} **Why do you need this?** 🎓 You are a student 🏫 You are an educator or academic institution {% endhint %} We routinely hear from students, teachers, professors, and university administrators that they’d love to use CARTO in the classroom. Here is how schools and individual students may make use of CARTO: * Individual Student Accounts: free CARTO accounts via GitHub Student Developer Pack * Educator Accounts: free CARTO accounts by request * Enterprise Accounts for Education: discounts and grants on a case by case basis *** #### **How can I get a Student account in CARTO?** Students can create a free CARTO account via [GitHub’s Student Developer Pack](http://education.github.com/pack). When they sign up for the pack, they’ll also get access to a ton of other free development tools! See the process and eligibility requirements below. *** #### **How can I get an Educator account?** Educators are also eligible for a free CARTO account. Request an Educator account by completing the following [request form](https://share.hsforms.com/1_dMkP1UzSsuY00Oz6zkccAa6if), attaching a document that accredits your educator status. We welcome educators from accredited institutions as well as bootcamps and similar training organizations. [–> Request your Educator account here](https://share.hsforms.com/1_dMkP1UzSsuY00Oz6zkccAa6if) *** #### **We need Enterprise capabilities for our institution or academic research, can you help?** Academic researchers and others in the education field, whether at a school, university, independent research center, or boot camp, can make use of CARTO Enterprise at a discount. [Contact sales](https://carto.com/#request-demo) to learn more. *** #### **What is the process for getting a CARTO Student account?** To verify that only eligible students are accessing CARTO, we take advantage of Github’s verification system. This means you will need to go through their channels to ensure you receive the proper student account: **Step 1:** Sign up for Github 1. Sign up for a free Github account, using your university issued email to do so: 1. ✅ `yourname@university.edu` 2. ❌ `yourname@gmail.com` 2. Here’s a video-tutorial with all the steps: {% embed url="" %} **Step 2:** Apply for the Github Education Pack * [Apply here](https://education.github.com/pack) with your GitHub account **To be eligible, you must** * Be a student aged 13+ and enrolled in a degree or diploma granting course of study * Verify who you are with one of the following: * a school-issued email address * provide a valid student identification card * other official proof of enrollment **Step 3:** Wait for verification and confirm Once you apply, Github will need to verify you are, in fact, a student. This could take from *1 hour to several days*. Please be patient and wait for your official verification, it is important for the process. Upon verification, you will receive an email from Github that you have access to the Education Pack If you have any questions regarding Github’s verification process, please reach out to their support team at . Please also keep an eye on your spam folder, as your university email policies might route the verification message there. **Step 4:** Claim your CARTO student account 🎉 Congratulations! You can now claim your free CARTO Student account here: This process will connect your GitHub account. Remember you should that URL for login too, although it will always be available from the general login page.

{% hint style="info" %} **Remember** To login to your CARTO Student account you’ll need to always use this specific URL: {% endhint %} *** #### **What can I do with a CARTO Student account, and what are its limitations?** A Student account gives you access to the same **Builder**, **Workflows**, **Data Explorer** and **Analytics Toolbox** features as other CARTO plans — individual features are generally not gated by plan type. The differences are in **seats**, **developer tokens**, and **quotas**: * **Single user** — a Student account has one seat (you). You can't invite additional editors or viewers. * **No API Access Tokens** — the API Access Token quota is 0, so you can't create them. Student accounts aren't intended for programmatic/API-driven or application-development use. * **No published applications** — building and hosting CARTO applications isn't available on the Student plan. * **CARTO QGIS Plugin is not supported** — see the question below. * **Data Observatory** — you can use public and sample datasets, but premium subscriptions aren't included. * **Time-limited** — a Student account is valid for one year (renewable while you remain an eligible student). * **Usage quotas** — map, geocoding, routing, isolines and compute quotas are sized for individual learning and coursework. If you need any of the above (extra seats, API tokens, application development, premium data), you can request an **Educator** account or talk to us about **Enterprise / Grant** options — see the questions above. *** #### **Can I use the CARTO QGIS Plugin with my Student account?** The CARTO QGIS Plugin is not currently available for Student accounts. Student accounts sign in via GitHub at , and the QGIS Plugin login screen doesn't offer a GitHub sign-in option — the student login link on that screen opens the CARTO web workspace instead of completing the login inside QGIS. This is a known limitation with no workaround at the moment; you can continue to use your Student account through the CARTO web platform. *** #### **Can I create API Access Tokens or use CARTO programmatically?** No. The Student plan includes 0 API Access Tokens, so the platform APIs and programmatic integrations aren't available on a Student account. If your project needs API access or application development, request an **Educator** account (free, by request) or contact us about an **Enterprise / Education** plan. *** #### **Can I add other people to my Student account?** No. A Student account is a single-seat account, so you can't invite additional editors or viewers. If you need to collaborate with a team, an **Educator** or **Enterprise** account is the right fit. *** #### **How long does my Student account last, and what happens when it expires?** Student accounts are valid for one year. As long as you're still an eligible student, you can renew through the [GitHub Student Developer Pack](https://education.github.com/pack). When an account expires it is first **suspended** and later **permanently deleted** after a grace period — you'll receive email reminders beforehand. Log in before the deletion date to keep your account and data; once an account is deleted, its data can't be recovered. *** #### **I can't log in to my Student account** Student accounts authenticate through GitHub, so always log in from (not the standard login page). Make sure you've completed GitHub's Student Developer Pack verification first — that step is handled by GitHub and can take from an hour to several days. If login still fails after verification, contact CARTO Support. *** #### **I am an educator and my course materials use the previous version of CARTO. What can I do?** Legacy CARTO accounts (`carto.com`) were retired in 2025. If your course materials were built on the previous platform, you can recreate them on the current CARTO platform: 1. Sign in to the current platform at (Student accounts use ). 2. Import your datasets through Data Explorer — see our [importing data guide](https://docs.carto.com/carto-user-manual/data-explorer/importing-data/). If you don't have your own data warehouse, you can use the CARTO Data Warehouse provided with your account. 3. Rebuild your maps with Builder. If you need help migrating your teaching materials, [contact CARTO Support](https://docs.carto.com/) and we'll be glad to assist. # Support Packages [What support packages are available at CARTO?](https://docs.carto.com/faqs/categories/support-packages/#what-support-packages-are-available-at-carto) [Who is entitled to Support?](https://docs.carto.com/faqs/categories/support-packages/#who-is-entitled-to-support) [What are CARTO Business Hours?](https://docs.carto.com/faqs/categories/support-packages/#what-are-carto-business-hours) [What are Customer Success Managers (CSMs)?](https://docs.carto.com/faqs/categories/support-packages/#what-are-customer-success-managers-csms) [What are Service Hours?](#what-are-service-hours) [How to submit an issue to our Support team?](https://docs.carto.com/faqs/categories/support-packages/#how-to-submit-an-issue-to-our-support-team) [What is the issue and severity classification?](https://docs.carto.com/faqs/categories/support-packages/#what-is-the-issue-and-severity-classification) [What are CARTO’s Target Response Times (business hours)?](https://docs.carto.com/faqs/categories/support-packages/#what-are-cartos-target-response-times-business-hours) *** ### **What support packages are available at CARTO?** CARTO offers comprehensive Support Packages to our enterprise customers. CARTO is committed to helping you make the most of your CARTO solution. These Packages are structured to help organizations at any stage of using location data to solve complex problems. We offer the following Packages with a combination of services to best suit your specific needs, available in both annual and pay-as-you-go subscription models. #### Annual Subscriptions A fixed yearly commitment that gives you predictable budgeting. Best suited for organizations with ongoing projects and a clear view of their support needs throughout the year.

Support Package	Standard	Premium	Elite	Individual
Support Access	email	email	email or videoconference	email
Documentation	✓	✓	✓	✓
Support Coverage	Business Hours (1 region)	Business Hours (2 regions)	24 / 7	Business Hours (1 region)
Target Response Times	Standard	Premium	Elite	Pro
Customer Success Manager (CSM)		✓	✓
Onboarding	Online	CSM-led	CSM-led	Online
Success Plans		✓	✓
Quarterly Business Reviews		✓	✓
Access to CARTO-organized communities of practice		✓	✓
Product Updates	Online	CSM-led review	CSM-led review	Online
Feature Request elevation			✓
Services Hours		max. 20h	max. 40h

#### Pay As You Go A flexible monthly billing model, well suited for organizations with variable or seasonal needs. Support tier is standard by default and can be upgraded at any point, keeping the selected tier in effect for the duration of the PAYG engagement.

Support Package	Standard	Premium	Elite	Individual
Support Access	email	email	email or videoconference	email
Documentation	✓	✓	✓	✓
Support Coverage	Business Hours (1 region)	Business Hours (2 regions)	24 / 7	Business Hours (1 region)
Target Response Times	Standard	Premium	Elite	Pro
Customer Success Manager (CSM)		Available after 1st year	Available after 1st year
Onboarding	Online	Online	Online	Online
Success Plans		Available after 1st year	Available after 1st year
Quarterly Business Reviews		Available after 1st year	Available after 1st year
Access to CARTO-organized communities of practice		✓	✓
Product Updates	Online	Online	Online	Online
Feature Request elevation			✓
Services Hours (monthly)		max. 2h	max. 4h

*** ### **Who is entitled to Support?** Users of the CARTO Platform are entitled to support according to their Support Package, described above. CARTO is not responsible for providing support to end users of CARTO-powered applications. *** ### **What are CARTO Business Hours?** CARTO Support provides business hours coverage across 3 regions: * European Region ( 9am - 6pm Central European Time (CET) ) * American Region ( 9am - 8pm Eastern Standard Time (ET) ) * APAC Region (8am - 5pm Singapore Time (SGT) ) Business hours coverage is determined by your selected Support Package. For those customers on a Standard Package, you will be offered the option of selecting 1 of the regions as your indicated coverage times. For those customers on a Premium Package, “business hours” are defined by the indicated hours across two regions. Customers with an Elite Support Package are provided with 24/7 support for P1 priority issues (see more below on issue classification). Customers with an Elite Support Package will be given specific access to information and guidance regarding how and when to leverage 24/7 support. CARTO works in good faith to respond to all submitted issues in a timely fashion. Slower than usual responses can be expected due to regional holidays of our Team. *** ### **What are Customer Success Managers (CSMs)?** Customer Success Managers at CARTO bring geospatial expertise and hands-on guidance in applying Location Intelligence to business needs, based on our experience working with hundreds of enterprise customers in diverse industries and fields. CSM’s also act as the “voice of the customer” communicating to and, as required, connecting customers with Product, Support, and other CARTO teams. *** ### **What are Service Hours?** Service Hours are pre-allocated blocks of expert time included with the Premium and Elite Support Packages. They can be used for activities that go beyond standard support — for example, technical guidance on advanced use cases, architecture reviews, custom enablement sessions, or hands-on assistance with specific projects. Service Hours are allocated annually or monthly (depending on your subscription) and must be used within that term. **Unused hours do not roll over to the following term** — they expire at the end of the term. We recommend planning their usage together with your Customer Success Manager early in the term to ensure you get the full value from them. *** ### **How to submit an issue to our Support team?** Support issues should be submitted via the indicated email address based on your selected Support Package. * Enterprise account users will contact Support with . * Elite accounts will have dedicated email addresses for P1 that will be shared when the Elite Support Package coverage starts. * For P2 and P3, they will contact support with . *** ### **What is the issue and severity classification?** All support issues received will be first triaged and assigned a prioritization level based on the severity of the reported issue. CARTO will work to first investigate and understand the issue at hand to ensure the appropriate severity level is assigned. CARTO classifies support issues as follows: | **Classification** | **Description** | | ------------------ | ----------------------------------------------------------- | | **P1** | Critical issue; full service is unusable | | **P2** | Issue with significant operational impact | | **P3** | Issue with limited operational impact and general questions | Customers should indicate the level of impact being experienced when submitting their support request. This will give CARTO’s Support Engineering team a sense of the potential impact and urgency of the issue. CARTO’s Support Engineering team will ultimately determine the issue severity based on initial investigation and correspondence with the issue submitter. *** ### **What are CARTO’s Target Response Times (business hours)?**


Severity	Standard	Premium	Elite	Individual
P1	4	2	1*	8
P2	6	4	2	12
P3	16	8	6	24

All response times are expressed in business hours, except for Elite P1 issues (\*) that are expressed in regular hours. # Security and Compliance [Is the CARTO Platform SOC 2 Type II-certified?](#is-the-carto-platform-soc-2-type-ii-certified) [Does it comply with GDPR, CCPA and other data privacy laws?](#does-it-comply-with-gdpr-ccpa-and-other-data-privacy-laws) [What are the password and login management controls in CARTO?](#what-are-the-password-and-login-management-controls-in-the-carto-platform) [When we create a connection to CARTO, does it make any copies of our data?](#when-we-create-a-connection-to-carto-does-it-make-any-copies-of-our-data) [How does CARTO manage our data?](#how-does-carto-manage-user-data) [Where is my data stored?](#where-is-my-data-stored) [How does CARTO manage security when a map, a workflow or an application are shared?](#how-does-carto-manage-security-when-a-map-workflow-or-an-application-are-shared) *** ### Is the CARTO Platform SOC 2 Type II-certified? Yes. As part of its SOC 2 Type II certification, CARTO undergoes annual auditing of its system and organization controls, performed by an independent, third-party certified auditor. CARTO’s latest SOC 2 Type II report is available upon request for customers and prospects. Please note that prospects must have signed an NDA (Non-disclosure agreement) with CARTO before receiving the SOC 2 Type II report. Visit to request the latest report. *** ### **Does it comply with GDPR, CCPA and other data privacy laws?** Yes. CARTO complies with GDPR, CCPA and other data privacy laws where applicable. You can read more about it in our [Privacy Policy.](https://carto.com/privacy) *** ### **What are the password and login management controls in CARTO?** There are three ways for users to access their CARTO accounts: * **Single Sign-On (SSO):** In this case, your organization will define the password requirements and will leverage all security policies such as rotation, MFA, etc. * **Sign in with Google:** The password requirements and policies are defined in your Google account preferences, which may be managed by your organization. * **Username/Password:** CARTO uses Auth0 to securely process the data and enforces sufficient length and complexity standards. If you're looking for password rotation, expiration or history controls we recommend you integrate [Single Sign-On](/carto-user-manual/settings/sso), so that you can set up and leverage your existing company policies. *** ### When we create a connection to CARTO, does it make any copies of our data? No, CARTO does not make any copies of the data available through your [Connections](/carto-user-manual/connections). CARTO is cloud-native by design, and we have no need to replicate your data — never. Maps, Workflows, and Applications built with CARTO will launch queries against live data in your own data warehouse (BigQuery, Snowflake, Redshift, Databricks, Oracle, PostgreSQL, etc) and the result of these queries is not stored for further uses, with the exception of a temporal cache layer for performance and cost optimization, that is encrypted and distributed securely. This applies to all kinds of deployments. *** ### How does CARTO manage our data? To understand how CARTO processes your data we first need to describe the three categories of data that CARTO processes: * **Connected Data:** This is the data in your data warehouse (BigQuery, Snowflake, Redshift, Databricks, Oracle, PostgreSQL, etc) that you'll be using in CARTO. As seen above, CARTO does not make any copies of your data. This data is encrypted in transit, and the credentials are never exposed in the frontend. * **User-generated Content:** These are the map details, workflows, credentials and configurations created by the users in a CARTO organization. User-generated Content is managed by CARTO. We carry out daily backups and encryption, except for self-hosted deployments. It is encrypted at rest and in transit. * **Personal Data:** This is the additional data needed by the platform to identify and provide service to the user such as settings, contact information, name, etc; User Data is managed by CARTO. We carry out daily backups and encryption, except for self-hosted deployments. It is encrypted at rest and in transit. *** ### Where is my data stored? * **Connected Data:** Stored in your connected cloud data warehouse, including the result of all analysis done in CARTO. * If you are using the [CARTO Data Warehouse](/carto-user-manual/connections/carto-data-warehouse), then it will be stored in the [organization's region of choice](/carto-user-manual/overview/carto-cloud-regions). * **User-generated Content:** This data is stored in the [organization's region of choice](/carto-user-manual/overview/carto-cloud-regions) for CARTO Cloud deployments. For Self-Hosted deployments this is stored in your Self-Hosted resources. * **Personal Data:** Personal user data is stored securely in a server in the United States, on the Google Cloud Platform. You can read more about it in our [Privacy Policy.](https://carto.com/privacy) *** ### How does CARTO manage security when a map, workflow or an application are shared? CARTO provides several controls to make sure viewers and editors don't gain unauthorized access to the underlying data of a map, workflow or application. * Editors can create connections to their data by providing credentials that are stored, encrypted, and never exposed in the browser in any case. These connections can then be shared with all editors in the organization (or with specific groups). * Editors can also [require viewer credentials on their connections](/carto-user-manual/connections/sharing-a-connection#require-viewer-credentials) for added security. * Maps, workflows and applications relying on a connection will stop working as soon as the credentials used are revoked. * Maps, workflows, and applications can be shared with all users within an organization (including viewers), or with specific groups, but **this does not grant them access to the connection**. * Published maps [can be protected with a password](/carto-user-manual/maps/sharing-and-collaboration#password-protected-maps) for additional security. # What is CARTO? CARTO is the leading Agentic GIS and Location Intelligence platform. It enables organizations to use AI, spatial data and analysis for more efficient delivery routes, better behavioral marketing, strategic store placements, and much more. Data Scientists, Developers, and Analysts use CARTO and its Agentic GIS approach to optimize business processes and predict future outcomes through the power of Spatial Data Science and AI Agents reasoning. CARTO is the only cloud-first spatial platform built for accelerated, modern GIS. It runs natively on top of your cloud data warehouse platform (e.g. Google BigQuery, Snowflake, AWS Redshift, Oracle, Databricks, PostgreSQL, etc.), providing easy access to highly scalable spatial analysis and visualization capabilities in the cloud - be it for analytics, app development, data engineering, AI-powered decision-making, and more. Users can use CARTO in both cloud and self-hosted deployments, giving enterprises full control over their data, and infrastructure while ensuring security, compliance, and seamless integration with existing systems. CARTO offers enterprise-grade secure connectivity to your own vetted AI models, authenticated through your organization’s credentials and proxy configuration. Supported providers include Google, Snowflake, AWS Bedrock, Databricks, Oracle, OpenAI, Anthropic, and more, ensuring full compliance, governance, and flexibility for enterprise AI deployments.

## Who uses CARTO? Different type of users leverage our platform in different ways, such as:

🧑‍💼 Data Analysts

A Data Analyst might use [Builder](/faqs/builder) to create maps and dashboards, and [Workflows](/faqs/workflows) to design analysis pipelines. They can also develop [AI Agents](/carto-user-manual/ai-agents) powered by their own [MCP Tools](/carto-user-manual/workflows/workflows-as-mcp-tools), making spatial insights accessible through natural language.

🧑‍💻 Data Engineers

A Data Engineering might automate [geospatial pipelines](/faqs/workflows) and enrich data from the [Data Observatory](/carto-user-manual/data-observatory), exposing curated results as [tools](/carto-for-agents/mcp-server) for [AI Agents](/carto-user-manual/ai-agents) and enterprise applications.

🧑‍🔬 Data Scientists

A Data Scientist might use [Workflows](/faqs/workflows) and the [Analytics Toolbox](/data-and-analysis/analytics-toolbox-overview) to engineer spatial features and perform advanced analyses, then visualize and share results through [Builder](/faqs/builder) dashboards. They might also leverage [AI Agents](/carto-user-manual/ai-agents) and [MCP Tools](/carto-for-agents/mcp-server) to explore correlations and generate insights conversationally.

🧑‍💻 Developers

A Developer might build scalable and performant [geospatial apps](/carto-for-developers/overview) faster and on top of their own cloud data warehouse by using the CARTO module in [deck.gl](https://github.com/CartoDB/gitbook-documentation/blob/master/carto-for-developers/key-concepts/carto-for-deck.gl), CARTO APIs, and custom [MCP tools](/carto-for-agents/mcp-server) that connect to internal data or trigger workflows.

📈 Analytics and GIS leaders

An Analytic and GIS Leader might empower teams across the organization to use spatial data effectively, from [Builder](/faqs/builder) dashboards and [Workflows](/faqs/workflows) for analysis to [AI Agents](/carto-user-manual/ai-agents) and [MCP Tools](/carto-for-agents/mcp-server) that make insights accessible through natural language.

🗺️ GIS Analysts

A GIS Analyst might use [Workflows](/faqs/workflows) to analyze data exposing them as [MCP Tools](/carto-user-manual/workflows/workflows-as-mcp-tools) to be reused by [AI Agents](/carto-user-manual/ai-agents) within [map-powered dashboards](/carto-user-manual/maps) or other systems, turning complex spatial analysis into modular and accessible insights

☁️ Cloud Architects

A Cloud Architect might implement CARTO to speed up the migration of geospatial workloads to the cloud.

### What makes CARTO unique? We believe that CARTO does some things extremely well — And those things make us unique versus other geospatial platforms:


Cloud Native Direct connection to your cloud data warehouse — no migration or ETLs needed. Use native SQL across the platform and leverage your data warehouse geospatial capabilities. Our Analytics Toolbox functions are installed and run natively in your data warehouse, expanding its geospatial capabilities. Streamlined security and governance by inheriting data and user access controls. Easy to ramp up for people with limited exposure to geospatial, unlike traditional GIS tools.
Scale and Performance Process millions and billions of records by leveraging your cloud data warehouse computational power. Full support for spatial indexing techniques such as H3, optimizing transformations, enrichment, and analysis for superior performance with large datasets. Create performant visualizations regardless of data scale using dynamic and static tiling strategies. Use Builder to create and share dashboards in minutes; create spatial workflows easily in Workflows, our no-code visual model builder Faster development of scalable geospatial applications by leveraging CARTO and Deck.gl, allowing you to focus on driving value with your application
Agentic GIS CARTO brings AI-powered spatial reasoning to the cloud with AI Agents capable of understanding, analyzing, and visualizing your data through natural language. Combine the scale of cloud-native processing with the adaptability of AI to assist in complex analyses, build workflows, and generate spatial insights conversationally. Securely connect CARTO to your own vetted AI models using your organization’s credentials and proxy. Bring CARTO into your own AI assistant with CARTO for Agents — connect Claude, ChatGPT, Gemini, Microsoft Copilot, and more through the CARTO MCP Server to create maps, run Workflows, and explore your data conversationally.

Cloud Native

Direct connection to your cloud data warehouse — no migration or ETLs needed.
Use native SQL across the platform and leverage your data warehouse geospatial capabilities.
Our Analytics Toolbox functions are installed and run natively in your data warehouse, expanding its geospatial capabilities.
Streamlined security and governance by inheriting data and user access controls.
Easy to ramp up for people with limited exposure to geospatial, unlike traditional GIS tools.

Scale and Performance

Process millions and billions of records by leveraging your cloud data warehouse computational power.
Full support for spatial indexing techniques such as H3, optimizing transformations, enrichment, and analysis for superior performance with large datasets.
Create performant visualizations regardless of data scale using dynamic and static tiling strategies.
Use Builder to create and share dashboards in minutes; create spatial workflows easily in Workflows, our no-code visual model builder
Faster development of scalable geospatial applications by leveraging CARTO and Deck.gl, allowing you to focus on driving value with your application

Agentic GIS

CARTO brings AI-powered spatial reasoning to the cloud with AI Agents capable of understanding, analyzing, and visualizing your data through natural language.
Combine the scale of cloud-native processing with the adaptability of AI to assist in complex analyses, build workflows, and generate spatial insights conversationally.
Securely connect CARTO to your own vetted AI models using your organization’s credentials and proxy.
Bring CARTO into your own AI assistant with CARTO for Agents — connect Claude, ChatGPT, Gemini, Microsoft Copilot, and more through the CARTO MCP Server to create maps, run Workflows, and explore your data conversationally.

## Components of the CARTO platform Depending on your usage of the CARTO platform, whether it’s for visualization, analysis, data access, or application development, you will be using different components of the platform. ### **Workspace** The central location of all your experience with CARTO; connect to multiple cloud data warehouses, explore your geospatial data, access Maps, Workflows and AI Agents and access the different CARTO tools. [Login or create an account](https://app.carto.com/login).

### **Builder** CARTO Builder offers powerful map making capabilities, interactive data visualizations, collaboration and publication options - everything running natively from your cloud data warehouse.[ Learn more](/carto-user-manual/maps).

### **AI Agents** CARTO AI Agents provide a powerful conversational interface that allows anyone, regardless of technical expertise, to ask questions in natural language and receive instant, actionable insights. This marks a fundamental shift beyond dashboards to a dynamic, intuitive way of exploring your geospatial data. [Learn more](/carto-user-manual/ai-agents).

### **Workflows** CARTO Workflows is a visual model builder that allows you to build complex spatial analyses and data preparation and transformation workflows without writing code. As with the rest of our platform, Workflows is fully cloud-native and runs in your own data warehouse. [Learn more](/carto-user-manual/workflows).

### **CARTO for Agents** CARTO for Agents brings the full platform to your AI assistant. Connect Claude, ChatGPT, Gemini, Microsoft Copilot, and more through the [CARTO MCP Server](/carto-for-agents/mcp-server) and create and edit maps, build and run Workflows, explore your data warehouse, and manage your organization — all in natural language. Coding agents get [Agent Skills](/carto-for-agents/agent-skills) and the [CARTO CLI](/carto-for-agents/cli) for scripting and automation. [Learn more](/carto-for-agents/carto-for-agents).

### **Platform APIs and libraries** For the Developer community, we have created a complete library of APIs, frameworks, connectors, and development tools to accelerate your spatial app development process. [View all libraries and APIs](/carto-for-developers/reference/carto-api).

### **Analytics Toolbox** The CARTO Analytics Toolbox is a suite of functions and procedures to easily enhance the geospatial capabilities available in the different cloud data warehouses. It contains more than 100 advanced spatial functions, grouped in different modules such as tiler, data, clustering, statistics, etc. [Learn more](https://docs.carto.com/analytics-toolbox/about-the-analytics-toolbox/).

### **Data Observatory** We catalog and distribute thousands of vetted public and premium spatial datasets, covering most global markets. These datasets are available across the different components of CARTO, so you can use them for data enrichment or as additional layers for your spatial apps and analyses. [Explore our Spatial Data Catalog](https://docs.carto.com/data-observatory/overview/getting-started/).

## Next steps Now that you're familiar with CARTO, here are some beginner-friendly next steps you can take to get started: 1. [Create a new CARTO organization](/carto-user-manual/overview/creating-your-carto-organization) if you haven't already: our 14-day free trial does not require a credit card and allows you for unlimited testing. 2. Read our first-steps guides to [connect to your data](/getting-started/quickstart-guides/connecting-to-your-data), [create your first map](/getting-started/quickstart-guides/creating-your-first-map), [get started with CARTO for Agents](/getting-started/quickstart-guides/connecting-carto-to-your-agents), [create your first agent](/carto-user-manual/ai-agents/creating-your-agent), [create your first workflow](/getting-started/quickstart-guides/creating-your-first-workflow), [create your first MCP tool](/carto-user-manual/workflows/workflows-as-mcp-tools) and [develop your first application](/getting-started/quickstart-guides/developing-your-first-application). 3. Discover our [CARTO Academy](https://academy.carto.com) where you will find easy-to-follow steps to build your first use cases using the CARTO platform. # Quickstart guides These guides will help you get started with CARTO. They're easy to follow with detailed steps, and will help you kickstart your project with your own connections, maps, workflows, and applications.

		Featuring			Cover image
Connecting to your data	Learn how to connect CARTO to your own cloud data warehouse and how to easily import your local geospatial files.	CARTO Workspace	Connecting to your data		Connections (1).png
Creating your first map	Create interactive dashboards and web maps with your geospatial data using our map-making tool, CARTO Builder.	CARTO Builder	Creating your first map		25.png
Creating your first workflow	Learn how to use CARTO to build spatial analysis and data preparation workflows with our visual model builder.	CARTO Workflows	Creating your first workflow		Captura de pantalla 2023-09-18 a las 13.24.45.png
Developing your first application	Build a public application with CARTO + deck.gl and learn how to create powerful geospatial apps faster than ever.	CARTO + deck.gl	Developing your first application	https://github.com/CartoDB/gitbook-documentation/blob/master/getting-started/quickstart-guides/broken-reference/README.md	Development.png
Connecting CARTO to your agents	Connect your AI assistant — Claude, ChatGPT, Gemini, and more — to CARTO and build your first map from a prompt.	CARTO for Agents	Connecting CARTO to your agents

# Connecting to your data While using demo data during your onboarding process is great for learning and exploring the platform, nothing feels more real than using your own data in CARTO to create stunning maps, powerful analyses, and interactive applications. The main way to use your own data in CARTO is to [**connect CARTO to your data warehouse**](#creating-your-first-connection)**,** but if you still don't have a data warehouse (or if you don't have your geospatial files there) you can also [import files from your computer or from a URL](#importing-your-first-file). But first, let's dig in a little bit to understand what happens when you connect your data to CARTO. ## CARTO connectivity explained The CARTO platform is cloud-native by design. This means that we will always query the live data in your data warehouse, and your data warehouse will return the results, removing the need for ETLs and other costly and inefficient systems. We never make a copy or store the data on our servers, which means: * If you change the data in your data warehouse, your map will also reflect the changes *(except cached results)* * If you add to or modify the data in your data warehouse, it will also be immediately available in CARTO for you to create maps, workflows, and more. Because of this, CARTO allows for unparalleled performance and scalability.

Now that we've reviewed the meaning and benefits of going cloud-native, let's create your first live connection to your data. *** ## Creating your first connection You can connect CARTO to your data in: * **Google BigQuery** * **Snowflake** * **Amazon Redshift** * **PostgreSQL** * **Databricks** * **Oracle** {% hint style="info" %} If you still don't use any of these data warehouses (or you aren't ready to connect just yet), you can skip this part and go directly to [Importing your first file](#importing-your-first-file). {% endhint %} Check out this video to learn how to create your first connection. The video shows a Google BigQuery connection, but the process is similar when connecting to other data warehouses. Each step is also explained in detail below the video: {% embed url="" %}

Step 1: Go to Workspace > Connections and create a new connection

Access your CARTO Workspace and click on Connections in the left menu. A list of your current connections will be shown, but since this is your first time, it will only contain a connection to the CARTO Data Warehouse. Click on "**Create your first connection**" to get started.

Step 2: Choose your Data Warehouse provider

As discussed, you can choose between any of the available data warehouses. Some of them will have an additional step to choose the *authentication method* you want to use to connect. *For example, to connect to Google BigQuery you can choose between a "Service Account" or the "Sign in with Google" method.*

Step 3: Finish the connection setup

Fill in the remaining fields to complete the connection. The information required is different depending on the data warehouse and the authentication method. Here you will find the full documentation for each option: * [Connecting to Google BigQuery](/carto-user-manual/connections/bigquery) * [Connecting to Snowflake](/carto-user-manual/connections/snowflake) * [Connecting to Amazon Redshift](/carto-user-manual/connections/redshift) * [Connecting to PostgreSQL](/carto-user-manual/connections/postgresql) * [Connecting to Databricks](/carto-user-manual/connections/databricks) * [Connecting to Oracle](/carto-user-manual/connections/oracle) If your data warehouse requires you to whitelist incoming connections, here is a link to [our IP addresses to whitelist](https://github.com/CartoDB/gitbook-documentation/blob/master/getting-started/quickstart-guides/broken-reference/README.md). You will also have the option to share your connection. Connections are private by default, but you can consider [sharing your connection](/carto-user-manual/connections/sharing-a-connection) if you want to collaborate with other users. **Connections can be edited at any time**, so don't worry about other advanced fields for now. Later in your CARTO journey, you will learn about the [Analytics Toolbox](/data-and-analysis/analytics-toolbox-overview) (our set of native geospatial functions for your data warehouse) and other exciting features.

Step 4: Test your connection

Click on "Connect" and let CARTO test your connection: * ❌ **If unsuccessful:** You will stay on the connections creation page and the error will give you more details about what's wrong. If you need assistance, our [Support Team](/faqs/support-packages) will be happy to help. Some things you should check: * Look for typos and double-check the data in each field * Check that your data warehouse is up and running * Make sure you have permission to read and write data in your data warehouse * ✅ **If successful:** You will be redirected to the list of connections and you will see a new card with your connection details. Go back to this card at any time to edit or delete the connection. 🎉 **Congratulations!** You have now connected your data to CARTO. A quick way to test and explore this data is to open the [Data Explorer](/carto-user-manual/data-explorer) and list tables coming from your data warehouse. If you click on a table you will immediately see metadata and a map preview. From here, you can start your next geospatial project!

*** ## Importing your first file If your geospatial data is not yet in the cloud, CARTO can help you import it. There are many solutions to move data to the cloud data warehouses, but not many support geospatial formats, so let's take advantage of the CARTO platform. Check out this video to learn how to import your first file. Each step is explained below the video: {% embed url="" fullWidth="false" %}

Step 1: Prepare your data

Before you start with your data import process, please make sure you've checked the [**import requirements**](/carto-user-manual/data-explorer/importing-data#supported-formats)**.** A few additional best practices: * We recommend you give the name `geom` to the column containing the geometries for maximum compatibility. * Check that your geometry data does not contain [invalid geometries](https://github.com/chrieke/geojson-invalid-geometry). These will be skipped in most cases, up to a certain threshold (see [error tolerance](/carto-user-manual/data-explorer/importing-data#supported-formats-1)), but could also cause the import process to fail.

Step 2: Go to Data Explorer and start importing data

Now that your data is ready, access your CARTO Workspace and click on Data Explorer in the left menu. Once there, click the "*Import data*" button in the top-right corner of the screen. Let's start our import process!

Step 3: Choose a file, a name, and a destination

There are two possible sources for your file: * **A local file on your computer**: Click 'Browse' and select a file from your computer. * **A file coming from a public URL**: Alternatively, you can provide the URL to the file. This URL must be publicly accessible by anyone on the internet. Please remember that CARTO won't sync this URL, it's a one-time import to your data warehouse. Now click "Continue" and you will see two settings: 1. First, check and customize the "**Imported table name"**. This is the name of the table that we will create with your data. 2. Next, navigate through your connections to **select a destination** (i.e. a location in your data warehouse) where we will create the new table with the imported data. If you're new to CARTO and you don't have any connections of your own, a safe way to get started is to import data into `CARTO Data Warehouse > organization data > shared`. Here you can [learn more about the CARTO Data Warehouse](/carto-user-manual/connections/carto-data-warehouse). Once you're ready, click "*Save here*" to continue.

Step 4: Choose a schema strategy

When importing your data, it's necessary to assign a valid data type (`STRING`, `NUMBER, etc.`) to each column, and these data types need to match those in the destination data warehouse. For example: `VARCHAR` is valid in Snowflake, but not in Google BigQuery. The combined structure of columns and their data types is called **schema.** There are two strategies for the schema: * **Let CARTO automatically define the schema:** CARTO will read your table and guess the schema based on the data. * **Customize the schema manually:** You will see a preview, and you can customize the data type for each column. Read more about [customizing the schema](/carto-user-manual/data-explorer/importing-data#custom-schema-limitations). For this guide, let CARTO automatically set the schema - it works well in most cases. Click "*Continue*". ![](https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-6af3d015b9d07b40ea1d3467b6a75ce8c716797b%2FScreenshot%202023-08-09%20at%2012.55.26.png?alt=media)

Step 5: Confirm and let CARTO take care of the import process

On the next screen, you will see a summary of your import, including the name of the file, the desired destination and table name, and the schema strategy. If everything looks okay, click "***Import***" and CARTO will start importing your file. While importing your file, a progress bar will appear. You can minimize this window and the process will continue to run in the background, even if you close the browser tab. Some tips to understand this process: * The larger the file, the longer the import will take. A 1 GB file could take up to a few minutes. * If there are rows with errors *(e.g. invalid geometries, invalid values for a column, etc.),* the process will continue without those rows until a certain threshold. Learn more about [error tolerance when importing files](/carto-user-manual/data-explorer/importing-data#supported-formats-1). * Finally, if there are too many errors or there's a major problem, an *error block* ❌ will appear with further details on why this import failed. If you need assistance, please contact our [Support Team](/faqs/support-packages).

Step 6: Use your imported data

Once the import process is finished, you can click on the "*Imported Successfully ✅*" block and it will redirect you to the Data Explorer, with that file opened. You can go back to this file at any time - it's already stored in your data warehouse! 🎉 **Congratulations!** From this page (which includes a map preview and a data preview), you can start creating maps and workflows.

*** ## Next steps Your data is now in CARTO! This is a major step toward unlocking all the potential that the platform has to offer. Using this data, there are a few options for what to do next: 1. Create a stunning map using [CARTO Builder](/carto-user-manual/maps), our map-making tool. 2. Use [CARTO Workflows](/carto-user-manual/workflows) to visually build a geospatial analysis block by block, with your data as a starting point or an input, with no coding skills required. 3. Use this data in a [simple public application created with CARTO + deck.gl](/carto-for-developers/guides/build-a-public-application). # Creating your first map Begin your journey with [CARTO Builder](/carto-user-manual/maps), our dedicated tool for crafting and sharing interactive web maps using your geospatial data. This guide introduces you to the core of CARTO Builder. From styling your layers to adding widgets and sharing an interactive map with other users; it's the ideal resource for both newcomers and those revisiting the foundational aspects of Builder. ### **Create a map** The *Maps* section enables you to create and manage maps built with CARTO Builder in the CARTO Workspace. From your *Maps* page, click *Create your first map*. This will open the CARTO's map-making tool, Builder.

### **Add your Data Source** 1. Start by clicking on "*Add Source from...*" button. In CARTO Data Warehouse, navigate to *demo\_data > demo\_tables* and select “fires\_worldwide” dataset.

*Add a source from CARTO Data Warehouse*

### Style the Layer Once your data source is selected, CARTO Builder will automatically generate the default layer. 2. It's a good practice to rename this layer for clarify. Let's call it "Fires". 3. Navigate to the Layer Style settings. Here, under the "Fill Color" option, you'll find "More Options". In this section, you can select "Frp" column to style the layer based on the fire radiative power. Remember to select a color palette that makes sense for your data.

*Style the layer based on fire radiative power*

4. For better visibility, specially at lower zoom levels, adjust the "Radius" to 1.5.

### Add Widgets Widgets elevate the user experience by facilitating data exploration. Users can derive insights by interactive with interconnected filters that not only relate to each other but also adapt based on the map's viewport. 5. Configure a [*Formula Widget*](/carto-user-manual/maps/widgets/formula-widget) to calculate and display the total number of recorded fires.

6. Set up a [*Category Widget*](/carto-user-manual/maps/widgets/category-widget) to compare the total number of fires that started at night versus those during the day.

7. Create a [*Histogram Widget*](/carto-user-manual/maps/widgets/histogram-widget) based on the "bright\_ti4" column to showcase the range and frequency of observed bright temperatures. Ensure you adjust the "*Custom min. value*" to 290 to filter out outliers.

### Enable Interactions 8. Enable Interactions on your layer. We will choose the "*Click*" option so that Interactions are displayed when users "click" over specific features within the map. Here you can also decide what specific information will be displayed in the pop-up as well as the labelling and formatting.

### Setting Up the Legend 9. Adjust the legend to clarify the color indicator of your layer, such as "Fire Radiative Power (FRP)" for better understanding. 10. Under the "*Layer Control*", activate the "*Layer Selector*". Also, ensure the legend is set to display when the map is loaded by enabling the "*Open the legend when loading the map*" option.

### Choosing the right Basemap 11. With CARTO Builder, you have a wide range of choices when it comes to basemaps. For our current data, the CARTO Dark Matter provides an apt background, highlighting the fires.

### Provide a Map Description Map descriptions are essential for providing context and enhancing user experience. 12. To edit the Map Description, click the "i" button at the top right corner. This will open an editable template. Our description field supports Markdown, allowing you to format text, insert links, images, and bullet lists for clearer, more engaging descriptions. For a preview, toggle to View mode by clicking the "eye" icon.

### Ready to share? 13. Before sharing, give your map a meaningful title. How about "Fires across the globe"?

14. Once named, the "*Share*" button becomes active. Open it and choose the **Public** mode. This way, your map becomes accessible to anyone with the link.

And voilà! Copy the map link, and you're ready to share.

# Creating your first workflow [CARTO Workflows](/carto-user-manual/workflows) is a visual model builder that allows you to build complex spatial analyses and data preparation and transformation workflows without writing code. As with the rest of our platform, Workflows is fully cloud-native and runs in your own data warehouse leveraging its full scalability. In order to learn more about the main sections of CARTO Workflows' interface and its available components, please check [this section](/carto-user-manual/workflows) of our documentation.

In this first example we will create drive-time isolines for selected retail locations and we will then enrich them with population data leveraging the power of the H3 spatial index. This tutorial includes some examples of simple data manipulation, including filtering, ordering and limiting datasets, plus some more advanced concepts such as polyfiling areas with H3 cells and joining data using a spatial index in common. As input data we will leverage a point-based dataset representing retail location that is available in the demo data accessible from the CARTO Data Warehouse connection (i.e. retail\_stores), and a table with data from CARTO's Spatial Feature dataset in the USA aggregated at H3 Resolution 8 (i.e. derived\_spatialfeatures\_usa\_h3res8\_v1\_yearly\_v2). Let's get to it! ### **Creating a workflow and loading your data** 1. In your CARTO Workspace under the Workflows tab, create a new workflow.

2. Select the data warehouse where you have the table with the point data accessible. We'll be using the CARTO Data Warehouse, which should be available to all users. 3. Navigate the data sources panel to locate your table, and drag it onto the canvas. In this example we will be using the `retail_stores` table available in demo data. You should be able to preview the data both in tabular and map format.

### **Filtering data to select the relevant stores** In this example, we want to select the 100 stores with the highest revenue, our top performing locations. 4. First, we want to eliminate irrelevant store types. Drag the **Select Distinct** component from the Data Preparation toolbox onto the canvas. Connect the stores source to the input side of this component (the left side) and change the column type to **storetype**. 5. Click run.

6. Once run, click on the Select Distinct component and switch to the data preview at the bottom of the window. You will see a list of all distinct store type values. In this example, let’s say we’re only interested in supermarkets. 7. To select supermarkets, add a **Simple Filter** component from the Data Preparation toolbox. 8. Connect the retail stores to the filter, and specify the **column** as storetype, the **operator** as equal to, and the **value** as Supermarket (it's case sensitive). 9. Run!

This leaves us with 10,202 stores. The next step is to select the top 100 stores in terms of revenue. 10. Add an **Order By** component from the Data Preparation toolbox and connect it to the top output from Simple Filter. Note that the top output is all features which match the filter, and the bottom is all of those which don't. 11. Change the column to revenue and the order to descending.

12. Next add a **Limit** component - again from Data Preparation - and change the limit to 100, connecting this to the output of Order By. 13. Click run, to select only the top 100 stores in terms of generated revenue.

### **Creating walk-time isolines around the stores** 14. Next, add a **Create Isolines** component from the Spatial Constructors toolbox. Join the output of Limit to this. 15. Change the **mode** to *walk*, the **range type** to time and **range limit** to 600 (10 minutes).

16. Click run to create 10-minute drive-time isolines. Note this is quite an intensive process compared to many other functions in Workflows (it's calling to an external location data services provider), and so may take a little longer to run.

### Leveraging the H3 spatial index to enrich geospatial data 17. We now add a second input table to the canvas, we will drag and drop the table `derived_spatialfeatures_usa_h3res8_v1_yearly_v2` from `demo_tables`. This table include different spatial features (e.g. population, POIs, climatology, urbanity level, etc.) aggregated at H3 grid with resolution 8.

18. In order to be able to join the population data with the areas around each retail store, we will use the component **H3 Polyfill** in order to compute the H3 grid cells in resolution 8 that cover each of the isolines around the stores. We configure the node by selecting the Geo column "geom", configuring the Resolution value to 8 and enabling the option to **Keep input table columns**.

19. Next step is to join both tables based on their H3 indices. For that, we will use the **Join** component. We select the columns named h3 present in both tables to perform the join operation.

20. Check in the results tab that now you have joined data coming from the retail\_stores table with data from CARTO's spatial features dataset.

21. As we now have multiple H3 grid cells for each retail store, what we want to do is to aggregate the population associated with the area around each store (the H3 polyfilled isoline). In order to do that we are going to use the **Group By** component, and we are going to aggregate the `population_joined` column with a SUM as the aggregation operation and we are going to group by the table by the `store_id` column.

22. Now, check that in the results what we have again is one row per retail store (i.e. 100 rows) and in each of them we have the store\_id and the result of the sum of the population\_joined values for the different H3 cells that were associated with the isoline around each store.

23. We are going to re-join with a **Join** component the data about the retail\_stores (including the point geometry) with the aggregated population we have now. We take the output of the previous **Limit** component and we add it to a new **Join** component together with the data we generated in the previous step. We will use the column `store_id` to join both tables.

### Adding annotations to your workflow A cool feature in CARTO Workflows is the possibility to add [annotations](https://docs.carto.com/carto-user-manual/workflows/workflow-canvas#annotations) in any area of the canvas, supporting the [Markdown syntax](https://www.markdownguide.org/basic-syntax/) (allowing for different levels of headers, text formats, images, etc.). This allows users to better explain the different steps performed in a workflow so other users can understand them. In order to add an annotation to your canvas you only need to click on the corresponding icon on the top toolbar and select the location of the canvas where you want to add it.

###

### Sharing and further exploring the results of your workflow There are multiple ways to share the results of your workflows, from [saving the results in a table](https://docs.carto.com/carto-user-manual/workflows/components/import-export#save_as_table) to [sending them via e-mail](https://docs.carto.com/carto-user-manual/workflows/components/import-export#send-by-email) to your colleagues. Additionally, note that from any step of your workflow (including that with the final saved table), you can create a map in [CARTO Builder](/carto-user-manual/maps) in order to build an interactive dashboard with the result of your workflow plus any of your other spatial data sources. 24. Finally we use the **Save as table** component to save the results as a new table in our data warehouse. We can then use the "Create map" option to build an interactive map to explore this data further.

### What next? Check our [gallery of workflow examples](https://academy.carto.com/creating-workflows/workflow-templates) to keep learning how to get the most of this tool for your data transformation and analysis pipelines. The examples showcase a wide range of scenarios and applications: from simple building blocks for your geospatial analysis to more complex, industry-specific workflows tailored to facilitate running specific geospatial use-cases. # Developing your first application You can find a step-by-step [guide to develop your first public application](/carto-for-developers/guides/build-a-public-application) in the CARTO for Developers documentation: Here you will learn the basic concepts required to create a public web application using CARTO, compatible with any Javascript Development Framework. With CARTO you don't need to be a geospatial expert to develop a geospatial application, so if you're a web developer you shouldn't have any issues following this guide. After completing this guide you will be familiar with the following concepts: * Scaffolding your application. * Adding a [basemap](/carto-for-developers/key-concepts/carto-for-deck.gl/basemaps) * Creating an [API Access Token](/carto-for-developers/key-concepts/authentication-methods/api-access-tokens) with limited access to your data warehouse. * Visualizing a dataset with [deck.gl](https://github.com/CartoDB/gitbook-documentation/blob/master/carto-for-developers/key-concepts/carto-for-deck.gl) * Publishing your app

Architecture diagram of our public application

{% hint style="info" %} During this guide, we're using the [CARTO Data Warehouse](/carto-user-manual/connections/carto-data-warehouse). The process explained here is also compatible with other Warehouses like BigQuery, Snowflake, Redshift, Databricks, Oracle, or Postgres. Instead of using `connection=carto_dw`, you need to use connection=\. {% endhint %} {% content-ref url="/pages/34FdmhCFM8q4NrXHgGUb" %} [Build a public application](/carto-for-developers/guides/build-a-public-application) {% endcontent-ref %} # Connecting CARTO to your agents This quickstart connects your AI assistant to CARTO and builds your first map from a natural-language prompt — no code, no CLI. You'll use the [CARTO MCP Server](/carto-for-agents/mcp-server), which plugs CARTO into Claude, ChatGPT, Gemini Enterprise, Microsoft Copilot Studio, and other AI clients. **What you'll need:** * A [CARTO account](https://carto.com/signup) with a connected data warehouse (the built-in CARTO Data Warehouse works fine). * An AI client that supports remote MCP servers — [Claude](/carto-for-agents/connect-your-platform/claude) is the quickest to set up. ## Step 1: Get your MCP Server URL In CARTO Workspace, go to **Developers > Workflow API & MCP Server** and copy your **MCP Server URL**. It looks like: ``` https://.api.carto.com/mcp/ ``` If your organization uses single sign-on, copy the **SSO login** URL instead. ## Step 2: Connect your AI client Add the URL as a new MCP server in your client, then sign in to CARTO when prompted. Claude connects with just the URL — nothing else to configure. * [Claude](/carto-for-agents/connect-your-platform/claude) (Claude.ai and Desktop) * [ChatGPT](/carto-for-agents/connect-your-platform/chatgpt) * [Microsoft Copilot Studio](/carto-for-agents/connect-your-platform/microsoft-copilot-studio) * [Google Gemini Enterprise](/carto-for-agents/connect-your-platform/google-gemini-enterprise) * [All platforms →](/carto-for-agents/connect-your-platform) {% hint style="info" %} Sign in over **OAuth** for the full experience — creating and editing maps, running Workflows, and admin. An [API Access Token](/carto-for-agents/mcp-server/connecting-with-api-tokens) is a quick read-and-discovery alternative (browse, query, and search — no authoring). {% endhint %} ## Step 3: Ask your agent to build a map Once connected, confirm the tools are live with a simple prompt: > **List my CARTO connections and the tables in each.** Then build your first map. Paste this prompt and adjust the table name to one of your own (or use a Data Observatory dataset): > **Explore my CARTO data, then create a Builder map from `..`. Pick a sensible geometry or spatial-index column, style it clearly, add a legend, and set the map to private. Show me the result and give me the link to open it in CARTO.** Your agent will explore the connection, inspect the table, compose the map, create it in CARTO Builder, and return a link. On [hosts that render maps inline](/carto-for-agents/connect-your-platform#which-platforms-render-maps-inline) (Claude.ai, ChatGPT, Claude Desktop), it also shows the map right in the conversation.

An agent building a CARTO map from a prompt and rendering it inline in the conversation — Example: an agent builds a map from a prompt and renders it inline

## Keep going Try these next: > **Add a histogram widget and a category filter to that map, then make it public.** > **Build a Workflow that filters this table to the last 30 days, spatially joins it to my regions table, aggregates by region, and saves the result. Then run it and summarize the output.** > **Enrich my stores table with population and income from the Data Observatory, then map the result.** ## Where to go next * [**CARTO MCP Server**](/carto-for-agents/mcp-server) — everything your agent can do, and how to connect each platform. * [**MCP Tools Reference**](/carto-for-agents/mcp-server/tools-reference) — the full tool catalog. * [**CARTO Agent Skills**](/carto-for-agents/agent-skills) — teach coding agents (Claude Code, Codex, Gemini CLI) the right CARTO patterns. * [**CARTO CLI**](/carto-for-agents/cli) — scripting, CI/CD, and advanced automation. # Overview **CARTO for Agents** brings the full CARTO platform to your AI assistant. Connect your favorite agent — Claude, ChatGPT, Gemini Enterprise, Microsoft Copilot Studio, and more — and create and edit maps, build and run workflows, explore your data warehouse, and manage your organization, all in natural language. Most teams get everything they need from two pieces: * [**CARTO MCP Server**](/carto-for-agents/mcp-server) — a hosted [Model Context Protocol](https://modelcontextprotocol.io/) server that plugs CARTO into any MCP-compatible AI client. Your agent lists connections, browses data, creates and edits Builder maps, authors and runs Workflows, renders maps inline, and reaches admin tools — over a single URL. This is the starting point for most users. * [**CARTO Agent Skills**](/carto-for-agents/agent-skills) — a public catalog of playbooks at [`CartoDB/agent-skills`](https://github.com/CartoDB/agent-skills) that teach coding agents (Claude Code, Codex, Gemini CLI, and others) the right patterns for driving CARTO, so they get it right the first time. For scripting, automation, and deeper administration, there's a third piece: * [**CARTO CLI**](/carto-for-agents/cli) — a command-line interface (`@carto/carto-cli`) that exposes nearly every platform operation as a script-friendly command. Ideal for pipelines and headless environments, for bulk and cross-organization operations, and for administration and auditing — including SQL over your usage logs. The most complete surface, for power users who want fine-grained control.

## Where to start | You want to… | Use this | | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Set CARTO up in your AI platform — Claude, ChatGPT, Gemini, Copilot, Snowflake, Databricks, coding agents, and more | [Connect your platform](/carto-for-agents/connect-your-platform) | | Understand the in-conversation tools — create maps, build workflows, explore data, and more — and how to authenticate | [CARTO MCP Server](/carto-for-agents/mcp-server) | | Give a coding agent (Claude Code, Codex, Gemini CLI) the right CARTO patterns | [CARTO Agent Skills](/carto-for-agents/agent-skills) | | Script CARTO from a terminal or CI/CD pipeline, run bulk or cross-org operations, or audit usage logs | [CARTO CLI](/carto-for-agents/cli) | | Expose your own analytical workflow as a tool an agent can call | [Workflows as MCP Tools](/carto-user-manual/workflows/workflows-as-mcp-tools) | {% hint style="success" %} **New here?** The fastest path is the [CARTO for Agents quickstart](/getting-started/quickstart-guides/connecting-carto-to-your-agents): connect an agent to the MCP Server and paste one prompt to build your first map. {% endhint %} ## How the pieces fit together The three surfaces are complementary, not competing. Pick the one that matches how you work — or combine them. * The **MCP Server** is the shortest path from an AI client to CARTO. It needs no install: you connect a URL, sign in, and your agent can immediately reach a broad set of platform tools. Best for chat clients (Claude, ChatGPT, Gemini, Copilot, Databricks, Snowflake) and any MCP-compatible host. * **Agent Skills** ride on top of coding agents that run on your machine. They don't replace the MCP Server or the CLI — they make the agent *use them well*, choosing the right approach, flags, SQL dialect, and job-handling pattern for each request. * The **CLI** runs locally and can be called by any agent that executes shell commands, or by you directly. It's the most complete surface — the right tool for automation and scripting, for bulk and cross-organization operations, and for administration and auditing, including querying usage logs with SQL. Workflows you build in CARTO can be published as new tools. The same published workflow is reachable from the MCP Server, referenced by the Skills, and callable from the CLI. {% hint style="info" %} Looking for the **AI Agents you build inside Builder maps** (in-product agents bound to a map's data and tools)? That's a different product surface — see [CARTO User Manual → AI Agents](/carto-user-manual/ai-agents). Want to **embed AI-powered map interaction in your own application**? See [CARTO for Developers → Build an AI-powered map application](/carto-for-developers/guides/build-an-ai-powered-map-application). {% endhint %} # Connect your platform Start here to bring CARTO into the AI platform you already use. Each guide covers how to set CARTO up in that platform — usually the [CARTO MCP Server](/carto-for-agents/mcp-server), and for coding agents also the [Agent Skills](/carto-for-agents/agent-skills) and the [CARTO CLI](/carto-for-agents/cli) where they add value. Before you start, get your **MCP Server URL** from CARTO Workspace under **Developers > Workflow API & MCP Server**, and decide [how to authenticate](/carto-for-agents/mcp-server#choose-how-to-authenticate) — OAuth for the full tool surface, or an API Access Token for read-and-discovery work. ## Chat and enterprise assistants Connect over the MCP Server and work with CARTO in the conversation.


Claude	Claude.ai and Claude Desktop. Connects with just the URL.	logo-claude.png	Claude
ChatGPT	Custom connectors in Developer Mode.	logo-chatgpt.png	ChatGPT
Microsoft Copilot Studio	CARTO as a tool for your Copilot agents.	logo-copilot-studio.png	Microsoft Copilot Studio
Google Gemini Enterprise	Custom MCP data store in AI Applications.	logo-gemini.png	Google Gemini Enterprise
Snowflake Cortex	External MCP server for Cortex agents.	logo-snowflake.png	Snowflake CoWork
Databricks	MCP service through the Unity AI Gateway.	logo-databricks.png	Databricks Genie Code
Oracle (OCI Generative AI)	Token-based MCP calling on the Responses API.	logo-oracle.png	Oracle (OCI Generative AI)

## Coding agents Connect over the MCP Server, and add the Agent Skills and CLI so the agent drives CARTO idiomatically and can script, automate, and administer.


Claude Code	MCP over the CLI, plus Skills and the CARTO CLI.	logo-claude-code.png	Claude Code
Codex	Remote MCP server in the Codex config, plus Skills.	logo-codex.png	Codex
GitHub Copilot	Remote MCP server in VS Code or the coding agent.	logo-github-copilot.png	GitHub Copilot
Antigravity	Remote MCP server in the agentic IDE.	logo-antigravity.png	Antigravity

## What you can set up in each platform | Surface | What it gives the platform | Where | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | [CARTO MCP Server](/carto-for-agents/mcp-server) | In-conversation tools: explore data, create and edit maps, build and run Workflows, admin. Works in every platform above. | All platforms | | [CARTO Agent Skills](/carto-for-agents/agent-skills) | Playbooks that teach coding agents the right CARTO patterns. | Coding agents | | [CARTO CLI](/carto-for-agents/cli) | Scripting, CI/CD, headless and bulk work, and deeper administration and auditing. | Coding agents, terminals | ## Which platforms render maps inline? CARTO's map tools render an interactive map directly in the chat only on platforms that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview#client-support) — **Claude.ai, ChatGPT, and Claude Desktop** today. On other platforms the agent still creates the map and returns its URL; open it in CARTO to view it. # Claude Claude.ai and Claude Desktop support **Client ID Metadata Document (CIMD)** registration, so CARTO can recognize them automatically. **No OAuth client needs to be created or registered.** Simply provide Claude with the CARTO MCP Server URL and sign in. Both Claude.ai and Claude Desktop can also [render CARTO maps inline](/carto-for-agents/connect-your-platform#which-platforms-render-maps-inline) in the conversation, providing a richer experience when working with CARTO maps and spatial data. {% hint style="info" %} This zero-configuration OAuth flow is enabled by CIMD support. Other MCP clients may use different OAuth registration flows See [Connecting with OAuth](/carto-for-agents/mcp-server/connecting-with-oauth#the-simplest-path-clients-that-support-cimd) for how CARTO handles clients that lack it. {% endhint %} For the terminal coding agent, see [Claude Code](/carto-for-agents/connect-your-platform/claude-code). ## Claude.ai (web) 1. In [Claude.ai](https://claude.ai), open **Settings → Connectors**. 2. Click **Add custom connector**. 3. Enter a name, such as `CARTO`, and paste your **MCP Server URL**. 4. Click **Add**, then **Connect**. 5. You’ll be redirected to CARTO. **Sign in to authorize access.** For more information, see Anthropic's official [Custom connectors using remote MCP documentation](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

## Claude Desktop 1. Open [Claude Desktop](https://claude.com/download?utm_source=chatgpt.com) and go to **Settings → Connectors**. 2. Click **Add custom connector**. 3. Enter a name, such as `CARTO`, and paste your **MCP Server URL**. 4. Click **Add**, then **Connect**. 5. Complete the **CARTO sign-in** when prompted. For more information, see Anthropic's [documentation on using connectors with Claude](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities)

{% hint style="info" %} Claude connects over OAuth, so the agent gets the **full tool surface** — creating and editing maps, authoring Workflows, and admin. If your org uses SSO, use the **SSO login** URL from the Workspace instead. {% endhint %} ## Add the CARTO Agent Skills [CARTO Agent Skills](/carto-for-agents/agent-skills) are playbooks that teach Claude how to use the CARTO tools well. They cover which tool to reach for, the right SQL dialect for each warehouse, and recipes for common spatial analyses. The skills ship as a plugin, so you install the whole catalog at once and it stays up to date. Plugins are available on all paid Claude plans. 1. In Claude.ai or Claude Desktop, open **Customize** in the left sidebar and go to the **Plugins** tab. 2. In **Personal plugins**, click **+** and select **Add marketplace**. 3. Choose **Add from a repository** and enter `CartoDB/agent-skills`. 4. Find **carto-skills** in the new marketplace and click **Install**. 5. Ask something CARTO-specific, such as "List my CARTO maps". Claude picks the matching skill on its own. The plugin is shared across Claude.ai, Claude Desktop and Cowork, so you only install it once. For more information, see Anthropic's [documentation on using plugins in Claude](https://support.claude.com/en/articles/13837440-use-plugins-in-claude). ### For organization admins Organization marketplaces sync from private or internal GitHub repositories only. To offer the skills to everyone, copy [`CartoDB/agent-skills`](https://github.com/CartoDB/agent-skills) into a private repository in your organization. Then go to **Organization settings > Plugins & skills**, click **Add > Sync from GitHub**, and enter that repository. You can set **carto-skills** to **Installed by default** so every member gets it. See Anthropic's [guide to managing plugins for your organization](https://support.claude.com/en/articles/13837433-manage-plugins-for-your-organization). ### Uploading individual skills If you can't use plugins, you can upload skills one at a time instead. Go to **Settings > Capabilities > Skills**, click **Upload skill**, and choose a ZIP from the **Download** column of the [Skills catalog](/carto-for-agents/agent-skills/skills-catalog). Uploaded skills don't update themselves, so download and upload them again to get a newer version. {% hint style="info" %} Skills build on each other, and uploading one doesn't add its dependencies. Start with the four utility skills (`carto-basics`, `carto-connect-datawarehouse`, `carto-query-datawarehouse`, `carto-explore-datawarehouse`) plus `carto-create-builder-maps`, `carto-render-inline-map` and `carto-preview-builder-map`. See [Dependencies and routing](/carto-for-agents/agent-skills/skills-catalog#dependencies-and-routing). {% endhint %} # Claude Code If you’re setting up [Claude Code](https://code.claude.com/docs/en/overview) with CARTO, that means you’ll want three integration layers: * **CARTO MCP Server**: gives Claude Code in-conversation access to CARTO tools. * **CARTO Agent Skills**: teaches the agent CARTO-specific workflows and conventions. * **CARTO CLI:** handles scripting, automation, and more advanced administration.

## Connect the MCP Server **No SPA OAuth client is required.** Claude Code is recognized by CARTO automatically. First, copy your **MCP Server URL** from **CARTO Workspace > Settings > CARTO MCP Server**. Then run: ```bash claude mcp add --transport http carto https://.api.carto.com/mcp/ ``` On first use, run `/mcp` inside Claude Code and choose **Authenticate**. Claude Code opens the CARTO login in your browser and completes the OAuth flow. {% hint style="info" %} Connecting over OAuth gives the agent the **full tool surface:** creating and editing maps, authoring Workflows, and admin. If your organization uses SSO, use the **SSO login URL from CARTO Workspace** instead. {% endhint %} ## Add the Agent Skills Install the [CARTO Agent Skills](/carto-for-agents/agent-skills) so Claude Code follows the recommended CARTO patterns – including choosing the right tool, SQL dialect, and job-handling approach. ```shellscript /plugin marketplace add CartoDB/agent-skills ``` Then install the CARTO skills: ```shellscript /plugin install carto-skills@carto-agent-skills ``` See [Agent Skills → Installation](/carto-for-agents/agent-skills/installation) for more details. ## Add the CLI for scripting and admin For scripting, CI/CD, headless runs, bulk or cross-organization operations, and deeper administration and auditing – such as querying usage logs with SQL – install the CARTO CLI: ```bash npm install -g @carto/carto-cli ``` Then authenticate: ```shellscript carto auth login ``` The **Agent Skills know when to reach for the CLI versus the MCP Server**, allowing Claude Code to choose the appropriate path for each request. # ChatGPT [ChatGPT](https://chatgpt.com/) connects to CARTO through a **custom MCP server** over OAuth, giving ChatGPT access to CARTO's MCP tools. ChatGPT can also [render CARTO maps inline](/carto-for-agents/connect-your-platform#which-platforms-render-maps-inline) in the conversation, providing a richer experience when working with CARTO maps and spatial data. ## Requirements * A **ChatGPT Business, Enterprise, or Edu** workspace with **Developer mode** enabled. Full MCP support, including write and modify actions, is currently available on these plans. Pro users can connect MCPs with read/fetch permissions. See [OpenAI's Developer mode and MCP apps documentation](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt?utm_source=chatgpt.com) * Your CARTO **MCP Server URL**. * A CARTO **SPA OAuth Client** with a **Client ID**. A client secret is supported and recommended for this setup. See [Connecting with OAuth](/carto-for-agents/mcp-server/connecting-with-oauth#1-create-the-client-in-carto). * Access to configure the OAuth callback URL on the CARTO SPA OAuth Client. ## Connecting via OAuth 1. In ChatGPT, open **Settings > Security and login**, scroll to **Developer mode**, and toggle it on. You may see an **“ELEVATED RISK”** warning; this is expected when enabling custom MCP servers. 2. Go to **Settings > Plugins > Browse plugins** and click the **+** button in the top-right. 3. In **New Plugin**, configure the MCP server: * **Name:** anything, such as `CARTO`. * **Connection:** leave as **Server URL**. * **URL:** your CARTO MCP Server URL.

4. Under **Authentication**, choose **OAuth**. 5. Expand **Advanced OAuth settings > Registration method** and change **CIMD** to **User-Defined OAuth Client**. Enter your CARTO **Client ID** and **Client Secret**, and add `offline_access` to the scopes. 6. Accept the **“I understand and want to continue”** warning and click **Create**. 7. **Before signing in**, register ChatGPT's OAuth callback URL on your CARTO client. In CARTO, open the SPA client under **Developers → Credentials → SPA OAuth Clients**, turn off **Use default logout/callback URLs and Origins**, and add: ``` https://chatgpt.com/connector/oauth/ ``` Use the exact `` from the authorization URL that ChatGPT opens. Save the CARTO client. 8. Return to ChatGPT, click **Sign in**, and complete the CARTO consent flow. {% hint style="warning" %} Leave the OAuth registration method set to **User-Defined OAuth Client**. Do not use **CIMD** for this ChatGPT connection. CARTO's CIMD flow is used for supported Claude clients. If you see **“Unknown client,”** create a new CARTO SPA OAuth Client and use its Client ID. {% endhint %} ## Read-only alternative If you don't control the CARTO OAuth client, you can use a CARTO [API Access Token](/carto-for-agents/mcp-server/connecting-with-api-tokens) instead of OAuth. Choose **Access token / API key** in the authentication settings and provide a token with the **MCP Server** scope. Add the **SQL**, **Maps**, or **LDS** scopes as needed for additional CARTO tools. This provides a [read-and-discovery subset](/carto-for-agents/mcp-server/connecting-with-api-tokens#what-a-token-unlocks) of the CARTO tool surface and does not enable map or Workflow authoring. # Codex [Codex](https://developers.openai.com/codex/) can work with CARTO through a remote MCP server, the CARTO Agent Skills, and the CARTO CLI. * **MCP** — gives Codex access to CARTO tools. * **Agent Skills** — gives Codex reusable CARTO-specific instructions and workflows. * **CARTO CLI** — provides command-line access for scripting, automation, and administration. Together, these let Codex use CARTO tools while following CARTO-specific patterns and workflows. > **Before you start:** Copy your **MCP Server URL** from CARTO Workspace under **Workspace > Settings > MCP Server** ## MCP ### Connect to the MCP Server Add CARTO using the Codex CLI: ``` codex mcp add carto --url https://.api.carto.com/mcp/ ``` Alternatively, add the server manually to `~/.codex/config.toml`: ``` [mcp_servers.carto]url = "https://.api.carto.com/mcp/"bearer_token_env_var = "CARTO_TOKEN" # optional; sent as Authorization: Bearer ``` Replace `` and `` with the values from your CARTO MCP Server URL. #### Authentication For **OAuth**, which provides the full CARTO tool surface, start the browser-based login: ``` codex mcp login carto ``` For **read-and-discovery access**, set `CARTO_TOKEN` to a CARTO [API Access Token](/carto-user-manual/developers/managing-credentials/api-access-tokens): ``` export CARTO_TOKEN="" ``` The token is sent as: ``` Authorization: Bearer ``` ## CARTO CLI Codex runs in a terminal, so the [CARTO CLI](/carto-for-agents/cli) can be used alongside MCP and Agent Skills for scripting, automation, and administration. Install the CLI: ``` npm install -g @carto/carto-cli ``` Authenticate: ``` carto auth login ``` The CLI is useful when a task is better suited to command-line operations, scripting, or CARTO administration than to an MCP tool call. ## Agent Skills [CARTO Agent Skills](/carto-for-agents/agent-skills) complement MCP and the CLI. They provide CARTO-specific instructions and workflows that help Codex use both interfaces consistently and idiomatically. Install the CARTO Agent Skills through the Codex plugin manifest. See [**Agent Skills → Installation**](/carto-for-agents/agent-skills/installation) for setup instructions. MCP provides Codex with access to CARTO tools, while the CLI provides command-line capabilities. Skills provide the guidance for using them effectively. # GitHub Copilot [GitHub Copilot](https://docs.github.com/en/copilot) can work with CARTO in three complementary ways: * **MCP Server:** gives Copilot access to CARTO tools such as data discovery, SQL, Data Observatory, and other MCP capabilities. * **CARTO CLI:** provides command-line access to CARTO for scripting, automation, and administration. * **Agent Skills:** provides Copilot with reusable instructions and workflows for working with CARTO. The MCP setup differs depending on whether you're using **VS Code** or the **Copilot coding agent**. > **Before you start:** Copy your **MCP Server URL** from CARTO Workspace under **Workspace > Settings > MCP Server** ## MCP ### In VS Code VS Code supports remote MCP servers through `.vscode/mcp.json`. You can create the configuration manually or run **MCP: Add Server** from the Command Palette. Add CARTO as a remote HTTP server: ```json { "servers": { "carto": { "type": "http", "url": "https://.api.carto.com/mcp/", "headers": { "Authorization": "Bearer ${input:carto_token}" } } } } ``` Replace `` and `` with the values from your CARTO MCP Server URL. Using an input variable keeps the CARTO [API Access Token](/carto-for-agents/mcp-server/connecting-with-api-tokens) out of the configuration file. Don't hardcode the token in `.vscode/mcp.json`. If CARTO advertises OAuth, an **Auth** action appears above the server entry. Select **Auth** to sign in and use the full CARTO tool surface. This requires **VS Code 1.101 or later**. If OAuth isn't available, use a CARTO **API Access Token** instead. For more information, see [VS Code's MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers). ### In the Copilot coding agent The repository-level **Copilot coding agent** supports remote HTTP MCP servers but does **not support OAuth**. Use a CARTO API Access Token instead. Store the token as a repository or organization secret with a `COPILOT_MCP_` prefix. For example: ``` COPILOT_MCP_CARTO_TOKEN ``` Configure the MCP server using `mcpServers`: ```json { "mcpServers": { "carto": { "type": "http", "url": "https://.api.carto.com/mcp/", "headers": { "Authorization": "Bearer $COPILOT_MCP_CARTO_TOKEN" }, "tools": ["*"] } } } ``` Replace `` and `` with the values from your CARTO MCP Server URL. The `tools` field controls which MCP tools the coding agent can use. Replace `"*"` with a focused list if you want to expose only specific CARTO tools. For more information, see [GitHub's documentation on extending Copilot coding agent with MCP](https://docs.github.com/en/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp). ## CARTO CLI Copilot has access to a terminal, so you can use the [CARTO CLI](/carto-for-agents/cli) alongside MCP for scripting, automation, and administration. Install the CLI: ``` npm install -g @carto/carto-cli ``` Authenticate: ``` carto auth login ``` The CLI is useful when the agent needs to perform command-line operations or when you want to automate CARTO tasks outside the MCP tool interface. ## Agent Skills **CARTO Agent Skills** provide reusable instructions and workflows that help Copilot work with CARTO consistently. Copilot does not currently provide a native installer for the [CARTO Agent Skills](/carto-for-agents/agent-skills) catalog. To use the same guidance, add the relevant CARTO skill playbooks to your repository's custom instructions, for example: ``` .github/copilot-instructions.md ``` This gives Copilot the CARTO-specific instructions and workflows, while MCP provides access to the underlying CARTO tools. # Antigravity [Google Antigravity](https://antigravity.google/) is an agentic development environment that can connect to CARTO through a remote MCP server. > **Before you start:** Copy your **MCP Server URL** from CARTO Workspace under **Workspace > Settings > MCP Server** ## Connect the MCP Server Antigravity supports remote MCP servers through its MCP configuration. Open **Manage MCP Servers > View raw config** and add CARTO to the `mcpServers` configuration: ```json { "mcpServers": { "carto": { "serverUrl": "https://.api.carto.com/mcp/", "headers": { "Authorization": "Bearer YOUR_CARTO_TOKEN" } } } } ``` Replace `` and `` with the values from your CARTO MCP Server URL. Use a CARTO [API Access Token](/carto-for-agents/mcp-server/connecting-with-api-tokens) in the header for the read-and-discovery subset. For the full surface, set up OAuth with a manual client ID and secret — CARTO doesn't support dynamic client registration for non-Claude clients (see [Connecting with OAuth](/carto-for-agents/mcp-server/connecting-with-oauth#everything-else-a-one-time-oauth-client)). {% hint style="info" %} **Version note:** Antigravity is a newer product and its MCP configuration options may change. Confirm the configuration path and supported authentication fields against the version of Antigravity you're using. {% endhint %} ## Skills and the CLI Because Antigravity is a full IDE with a terminal, you can also use the [CARTO CLI](/carto-for-agents/cli) for scripting, automation, and administration. Antigravity supports the `SKILL.md` format used by CARTO Agent Skills. You can add CARTO skills by placing the skill folders in your skills directory: * **Workspace:** `.agents/skills/` * **Global:** `~/.gemini/config/skills/` The exact skills directory can vary by Antigravity version, so confirm the current path in your installed version before adding skills. The CARTO CLI and Agent Skills are complementary to the MCP connection: MCP gives the agent access to CARTO tools, while the CLI and skills can provide additional instructions and workflows for working with CARTO from the development environment. # Microsoft Copilot Studio [Microsoft Copilot Studio](https://www.microsoft.com/en-us/microsoft-copilot/microsoft-copilot-studio) connects to CARTO as an **MCP tool** for your Copilot agents. A maker can configure the connection directly in Copilot Studio, and OAuth gives the agent access to the **full CARTO tool surface**. You can also upload the [CARTO Agent Skills](/carto-for-agents/agent-skills) to the same agent so it uses the CARTO tools well. ## Requirements * A Microsoft 365 account with a **Copilot Studio license**. * Your CARTO **MCP Server URL**. * For the full tool surface, a CARTO **SPA OAuth Client** with a **Client ID and Secret**. See [Connecting with OAuth](/carto-for-agents/mcp-server/connecting-with-oauth#1-create-the-client-in-carto). * **Generative orchestration** must be enabled for the agent. Otherwise, the MCP tools won't be invoked. {% hint style="info" %} **Generative orchestration must be enabled for the agent to use MCP tools.** See Microsoft's [MCP documentation for Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/agent-extend-action-mcp?utm_source=chatgpt.com). {% endhint %} ## Connecting via OAuth OAuth provides access to the **full CARTO tool surface**, including map and Workflow authoring. 1. In CARTO, create a **SPA OAuth Client** under **Developers > Credentials > SPA OAuth Clients**. * For **Application Login URI**, a placeholder such as `https://global.consent.azure-apim.net/redirect` is sufficient. * Keep the **Client ID** and **Client Secret**. 2. In Copilot Studio, open your agent, go to **Tools > Add a tool > Add new MCP**. 3. Configure the MCP connection: * **Server URL:** your CARTO MCP Server URL. * **Authentication: OAuth 2.0**, Configuration type **Manual**. * **Authorization URL:** `https://auth.carto.com/authorize` * **Token URL** / **Refresh URL:** `https://auth.carto.com/oauth/token` * **Scopes:** `openid profile email offline_access read:workflows write:workflows` * **Client ID / Secret:** from step 1.

4. Save the configuration. Copilot Studio generates a **per-connector redirect URL** that ends in a connector-specific ID, for example `https://global.consent.azure-apim.net/redirect/`. Copy it. 5. Back in CARTO, open the SPA OAuth Client and turn off **Use default logout/callback URLs and Origins**. Add the Copilot-generated URL to **Allowed Callback URLs**, then save the client. * Use the full per-connector URL, not the bare `https://global.consent.azure-apim.net/redirect` placeholder from step 1. The bare URL won't complete sign-in. * If you recreate or rename the MCP Server in Copilot Studio, it gets a new redirect URL. Add the new one to **Allowed Callback URLs**. 6. In Copilot Studio, create the connection and complete the **CARTO sign-in** in the popup. {% hint style="warning" %} Don't use Copilot Studio's **Dynamic discovery** option. It relies on dynamic client registration, which CARTO doesn't use. Always choose **Manual**. {% endhint %} {% hint style="info" %} **Two-step connection:** The connection showing as active in the authoring screen isn't always enough. When the agent is used in chat, the end user may need to complete a second connection through **Open connection manager → Connect → Submit**, or click **Retry** in the chat. Each user connects individually. This is expected. {% endhint %} ## Read-only alternative For **browse-and-query use cases**, you can skip OAuth and use a CARTO API Access Token instead. 1. In Copilot Studio, open your agent and go to **Tools > Add a tool > Add new MCP**. 2. Enter the **Server name**, **Description**, and **Server URL**. 3. Under **Authentication**, select **API key**. * **Type:** **Header** * **Header name:** `Authorization` 4. Create a connection using: `Bearer ` Include the `Bearer` prefix. 5. On your first message, complete the connection prompt by selecting **Connect > Submit** and wait for the connection to show as **Connected**. This provides the [**read-and-discovery subset**](/carto-for-agents/mcp-server/connecting-with-api-tokens#what-a-token-unlocks) **of the CARTO tool surface**. It does not enable map or Workflow authoring, and the available tools depend on the data API scopes carried by the CARTO API Access Token {% hint style="warning" %} If both an OAuth MCP tool and an API-key MCP tool are enabled, disable one. Otherwise, the orchestrator may select the API-key connection and expose the smaller read-and-discovery tool surface instead of the full OAuth surface. {% endhint %} ## Add the CARTO Agent Skills [CARTO Agent Skills](/carto-for-agents/agent-skills) are playbooks that teach the agent how to use the CARTO tools well. They cover which tool to reach for, the right SQL dialect for each warehouse, and recipes for common spatial analyses. You add them to the same agent that has the CARTO MCP tool. 1. **Download the skills.** Each skill is a ZIP file in the **Download** column of the [Skills catalog](/carto-for-agents/agent-skills/skills-catalog). 2. **Open the skill upload.** In Copilot Studio, open your agent on the **Build** tab. Next to **Skills**, click **+**, then choose **Upload a skill**. 3. **Upload each skill.** Drag and drop a skill ZIP, or click to choose it. Each ZIP holds one skill, so repeat this for every skill you want. 4. **Use them.** Ask something CARTO-specific, such as "List my CARTO maps". The agent picks the matching skill and calls the CARTO MCP tool.

Add skill dialog in Copilot Studio with the Upload a skill tab selected

{% hint style="info" %} Skills build on each other, and uploading one doesn't add its dependencies. Start with the four utility skills (`carto-basics`, `carto-connect-datawarehouse`, `carto-query-datawarehouse`, `carto-explore-datawarehouse`) plus `carto-create-builder-maps`. Add use-case skills such as `carto-hotspot-analysis` after that. See [Dependencies and routing](/carto-for-agents/agent-skills/skills-catalog#dependencies-and-routing). {% endhint %} # Google Gemini Enterprise [Gemini Enterprise](https://cloud.google.com/gemini/enterprise) connects to CARTO through a **custom MCP server data store**, configured in the Google Cloud console. Once connected, you can also upload the [CARTO Agent Skills](/carto-for-agents/agent-skills) so the agent uses the CARTO tools well. ## Requirements * A **Gemini Enterprise** license and a Google Cloud project. * The **Discovery Engine Editor** role (`roles/discoveryengine.editor`) to create the data store. * Your CARTO [MCP Server URL](/carto-for-agents/mcp-server#get-your-mcp-server-url). * A CARTO **SPA OAuth Client**. You create it in the [OAuth step](#2-connect-via-oauth) below. * For Agent Skills, an administrator with the **Gemini Enterprise Admin** role (`roles/discoveryengine.agentspaceAdmin`). {% hint style="info" %} Custom MCP lives under **Data Stores**, not under Agents or Actions. Admin console: [console.cloud.google.com/gen-app-builder](https://console.cloud.google.com/gen-app-builder). {% endhint %}

## Connect the CARTO MCP Server ### 1. Create the data store 1. In Google Cloud Console, open **AI Applications > Data stores > Create data store**. 2. Under **MCP servers**, pick the **Custom MCP Server** card and click **Add MCP server**. 3. Under **MCP Server Configuration**, choose **OAuth 2.0**. ### 2. Connect via OAuth 1. In CARTO, go to **Developers > Credentials > SPA OAuth Clients** and click **Create new > SPA OAuth Client**. Set the **Application Login URL** to Gemini Enterprise's redirect URI: ``` https://vertexaisearch.cloud.google.com/oauth-redirect ``` Save, then copy the **Client ID** and **Client Secret**. 2. Back in Google Cloud Console, fill in the **MCP Server Configuration** fields: | Field | Value | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | MCP Server URL | Your [MCP Server URL](/carto-for-agents/mcp-server#get-your-mcp-server-url). Use the **SSO login** URL if your organization signs in through SSO. | | Authorization URL | `https://auth.carto.com/authorize` | | Authorization URL Parameters | `&audience=carto-cloud-native-api` | | Token URL | `https://auth.carto.com/oauth/token` | | Client ID / Client Secret | From the SPA OAuth Client you just created | | Scopes | `openid profile email read:workflows write:workflows` |

The &audience=carto-cloud-native-api parameter is easy to miss. Without it, sign-in appears to succeed but the connection can't use any CARTO tools.

3. Click **Verify Auth** and complete the CARTO sign-in. If it fails, see [Troubleshooting](#troubleshooting). 4. Click **Continue**, name the data connector, select a pricing tier, and click **Create**. 5. Wait until the connector status changes from **Creating** to **Active**. This can take a few minutes; refresh the page to check. 6. Open the data store, go to the **Actions** tab, and click **Reload custom actions** to fetch CARTO's tool list. 7. Enable the tools you want to use. All tools are disabled by default.

{% hint style="warning" %} Registering an MCP server creates a **billable data store**, even when it isn't linked to an app. Remove data stores you no longer need. {% endhint %} {% hint style="info" %} Gemini Enterprise can't render maps inline, so leave the `view_map` tool disabled or ask the agent for the map URL and open it in CARTO. {% endhint %} ### 3. Link the data store to your Gemini Enterprise app 1. In **AI Applications**, open **Apps**.

2. Create a Gemini Enterprise app or open an existing one.

3. On the **Connected data stores** tab, click **Connect an existing data store** and select the CARTO data store you just created.

4. In the Gemini Enterprise chat, authorize the CARTO connector when prompted.

## Add the CARTO Agent Skills [CARTO Agent Skills](/carto-for-agents/agent-skills) are playbooks that teach the agent how to use the CARTO tools well: which tool to reach for, the right SQL dialect per warehouse, and recipes for common spatial analyses. 1. **Enable skills.** An administrator opens your app in Google Cloud Console, goes to **Configurations > Feature Management**, and turns on **Enable skills**. Until then, the **Skills** menu doesn't appear in Gemini Enterprise. 2. **Upload the skills.** From the **Skills** menu, upload each CARTO skill as a ZIP file. You can select several at once. See [Agent Skills → Installation](/carto-for-agents/agent-skills/installation) for how the skills are distributed. 3. **Use them.** Ask something CARTO-specific, such as "List my CARTO maps". The agent picks the matching skill, or you can call one with `@` and the skill name. ## Troubleshooting * **"Callback URL mismatch"** — the SPA OAuth Client's **Application Login URL** isn't `https://vertexaisearch.cloud.google.com/oauth-redirect`. Fix it in **Developers > Credentials > SPA OAuth Clients** and click **Verify Auth** again. * **"\[401010] Unauthorized"** — you signed in to CARTO as a user from a different organization than the one that owns the SPA OAuth Client. Sign out and sign in with the right user. * **"Failed to reload custom actions"** — the connector is still **Creating**. Wait until it's **Active** and retry. * **Sign-in works but there are no tools** — the **Authorization URL Parameters** field is missing `&audience=carto-cloud-native-api`, or the MCP Server URL was typed by hand. Fix it and click **Reload custom actions**. * **Sign-in doesn't use your identity provider** — your organization uses SSO. Use the **SSO login** URL as the MCP Server URL. For general OAuth issues, see [Connecting with OAuth](/carto-for-agents/mcp-server/connecting-with-oauth#troubleshooting). # Snowflake CoWork [Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp-connectors) connects to CARTO through an **external MCP server** configured as an MCP Connector. You can create the connector from the Snowflake UI or with SQL. Once configured, the connector can be added to a **Cortex Agent**. Snowflake also supports MCP Connectors in [Snowflake CoWork](https://docs.snowflake.com/en/user-guide/snowflake-cortex/snowflake-cowork/integrate-tools). {% hint style="info" %} CoWork is Snowflake's chat surface, where CARTO is reached through an agent you create and publish. For [Snowflake CoCo](/carto-for-agents/connect-your-platform/snowflake-coco), the coding agent, CARTO is configured differently: MCP, the CARTO CLI and the Agent Skills all apply there. {% endhint %} ## Requirements Before you start, you need: * **ACCOUNTADMIN** access to the Snowflake account. * Your CARTO **MCP Server URL**. You also need a **CARTO SPA OAuth Client**. The client must be **confidential** and have a **Client Secret**. Snowflake does not support public or PKCE-only clients for this integration, and static API tokens are not supported. ## Connect via OAuth OAuth is the authentication method used for the CARTO MCP connection. ### 1. Create a CARTO SPA OAuth Client In CARTO, create a **SPA OAuth Client** under **Developers > Credentials > SPA OAuth Clients**. * Configure the client as **confidential** so that it has a **Client Secret**. * Keep the **Client ID** and **Client Secret**. You will need them when configuring the Snowflake MCP Connector. Before continuing, register Snowflake's OAuth callback URL with the client. In the SPA OAuth Client, disable **Use default logout/callback URLs and Origins** and add: ``` https://identity.snowflake.com/oauth2/callback ``` ### 2. Create the MCP Connector You can create the connector from the [Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp-connectors) UI or with SQL. Both create the same Snowflake objects. #### Snowflake UI Go to **Settings > MCP connectors > Add MCP Connector**

Fill in:

Field	Value
Location	A real database and schema.
Name	Anything, for example `carto_mcp_server`
Description	What the connector is for. Snowflake shows this to the agent
API Integration	Standard OAuth
Server URL	Your MCP Server URL
Authorization endpoint	`https://auth.carto.com/authorize`
Token endpoint	`https://auth.carto.com/oauth/token`
OAuth Client ID/Secret	From your SPA client
Scopes	`openid,profile,email,read:workflows,write:workflows`

{% hint style="info" %} Do not use the **Dynamic Client Registration (DCR)** tab. Select **Standard OAuth** and enter the CARTO OAuth credentials manually. For more information, see [Snowflake's MCP Connector documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp-connectors). {% endhint %} #### SQL Run the following as **ACCOUNTADMIN**. Create the API Integration: ```sql CREATE API INTEGRATION CARTO_MCP_OAUTH2 API_PROVIDER = external_mcp API_ALLOWED_PREFIXES = ('https://.api.carto.com') API_USER_AUTHENTICATION = ( TYPE = OAUTH2 OAUTH_GRANT = AUTHORIZATION_CODE OAUTH_CLIENT_ID = '' OAUTH_CLIENT_SECRET = '' OAUTH_TOKEN_ENDPOINT = 'https://auth.carto.com/oauth/token' OAUTH_AUTHORIZATION_ENDPOINT = 'https://auth.carto.com/authorize' OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_BASIC OAUTH_ALLOWED_SCOPES = ('openid','profile','email','read:workflows','write:workflows')) ENABLED = TRUE; ``` Then create the external MCP server: ```sql CREATE EXTERNAL MCP SERVER CARTO_MCP_SERVER WITH DISPLAY_NAME = 'CARTO MCP' URL = 'https://.api.carto.com/mcp/' API_INTEGRATION = CARTO_MCP_OAUTH2; ``` {% hint style="info" %} Replace `` and `` with the values from your CARTO MCP Server URL. `OAUTH_GRANT = AUTHORIZATION_CODE` is required for this configuration because the CARTO SPA client uses the authorization-code flow. `CREATE OR REPLACE` is not supported for this API integration type. To change the integration, drop it and create it again. {% endhint %} ### 3. Grant access The role that creates and uses the agent needs `USAGE` on the following objects: * the **API integration** * the **external MCP server** * the **database** * the **schema** If you created the connector in the UI, use the following command to find the generated objects: ```sql SHOW EXTERNAL MCP SERVERS; ``` Then, as **ACCOUNTADMIN**, grant access to the role used by the agent: ```sql GRANT USAGE ON INTEGRATION CARTO_MCP_OAUTH2 TO ROLE ; GRANT USAGE ON EXTERNAL MCP SERVER CARTO_MCP_SERVER TO ROLE ; GRANT USAGE ON DATABASE TO ROLE ; GRANT USAGE ON SCHEMA . TO ROLE ; ``` You can also manage access to the agent from its **Access** tab. See [Snowflake's MCP Connector documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp-connectors) for more information about permissions. ### 4. Add the MCP Connector to an Agent In the Snowflake UI, go to: **Agents > open your agent > Configuration > MCP > Add to agent** Select the CARTO MCP Connector and complete the **Connect** consent flow. This signs you in to CARTO and authorizes the connection. For the full agent configuration flow, see [Snowflake's Cortex Agents documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents) ### 5. Add the CARTO Agent Skills This step is optional. [CARTO Agent Skills](/carto-for-agents/agent-skills) are playbooks that teach an agent to drive CARTO idiomatically, and Snowflake agents can load them from a Git repository. The catalog is public, so no credentials are required. Run the following as **ACCOUNTADMIN**: ```sql CREATE OR REPLACE API INTEGRATION github_cartodb API_PROVIDER = git_https_api API_ALLOWED_PREFIXES = ('https://github.com/CartoDB') ENABLED = TRUE; CREATE OR REPLACE GIT REPOSITORY ..carto_agent_skills API_INTEGRATION = github_cartodb ORIGIN = 'https://github.com/CartoDB/agent-skills'; ALTER GIT REPOSITORY ..carto_agent_skills FETCH; GRANT READ ON GIT REPOSITORY ..carto_agent_skills TO ROLE ; ``` Then, in the agent's **Configuration > Skills > Add skill**, point at a skill folder in the repository: ``` @..carto_agent_skills/branches/master/skills/carto-create-builder-maps ``` {% hint style="info" %} Skills are added one at a time. There is no way to attach the whole catalog at once, so start with `carto-create-builder-maps` and `carto-basics`. A Git repository is an internal stage, so it requires `GRANT READ` rather than `GRANT USAGE`. {% endhint %} ### 6. Publish the agent to Snowflake CoWork The agent is available in [Snowflake CoWork](https://docs.snowflake.com/en/user-guide/snowflake-cortex/snowflake-cowork/integrate-tools) once it is published and added to CoWork. 1. Select **Save**, then **Publish**. A draft agent does not appear in CoWork. 2. Next to the agent name, open the **⋮** menu and select **Add to Snowflake CoWork**. 3. In Snowflake CoWork, go to **Capabilities > MCP Connectors** and select **Connect** on the CARTO connector. This completes the OAuth consent and signs you in to CARTO. Each person who uses the agent does this once. 4. Start a **New chat** and select the agent. {% hint style="info" %} Access is per user. Each person authorizes with their own CARTO account, and the agent inherits that account's CARTO permissions: the connections, maps and workflows that account can reach. {% endhint %} ### 7. Test the connection Snowflake can create the API integration and external MCP server even if the OAuth credentials are invalid. The integration may appear healthy until the agent actually connects to CARTO. **Always run the agent before considering the setup complete.** Ask the agent to use a CARTO tool or describe the tools available to it. If you see an error such as: ``` Insufficient privileges to operate on Integration ``` check the `USAGE` grants on the API integration and external MCP server. For information about MCP tools and how clients discover and invoke them, see the [MCP Tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools). {% hint style="info" %} Maps do not render inside Snowflake. Inline rendering requires MCP Apps support, which is available on [a subset of platforms](/carto-for-agents/connect-your-platform#which-platforms-render-maps-inline). The agent creates the map and returns its URL, which you open in CARTO Builder. {% endhint %} # Snowflake CoCo [Snowflake CoCo](https://docs.snowflake.com/en/user-guide/cortex-code/cortex-code) is Snowflake's coding agent, available in Snowsight, as a desktop IDE, and as a CLI that runs in your local shell. It can work with CARTO through a remote MCP server, the CARTO Agent Skills, and the CARTO CLI. * **CARTO MCP:** gives CoCo access to CARTO tools. * **CARTO Agent Skills:** gives CoCo reusable CARTO-specific instructions and workflows. * **CARTO CLI:** provides command-line access for scripting, automation, and administration. Together, these let CoCo use CARTO tools while following CARTO-specific patterns and processes. {% hint style="info" %} CoCo is the coding agent. For the chat surface, where CARTO is reached through a Cortex agent and an MCP Connector, see [Snowflake CoWork](/carto-for-agents/connect-your-platform/snowflake-cowork). {% endhint %} ## MCP ### Connect to the MCP Server First, copy your **MCP Server URL** from **CARTO Workspace > Settings > CARTO MCP Server**. Then add CARTO with the CoCo CLI: ``` cortex mcp add carto https://.api.carto.com/mcp/ --type http ``` Alternatively, add the server manually to `~/.snowflake/cortex/mcp.json`: ```json { "mcpServers": { "carto": { "type": "http", "url": "https://.api.carto.com/mcp/", "oauth": { "client_id": "", "redirect_port": 8585, "scope": "openid profile email read:workflows write:workflows" } } } } ``` Replace `` and `` with the values from your CARTO MCP Server URL. Use `cortex mcp list` to confirm the server is registered. ### Authentication CoCo uses OAuth to authenticate to CARTO. Before connecting the MCP server, create and configure a SPA OAuth Client in CARTO. #### **1. Create a SPA OAuth Client** In CARTO, go to **Developers > Credentials > SPA OAuth Clients** and create a new client. #### **2. Configure the callback URL** CoCo uses a local callback to complete the OAuth flow. When configuring the SPA OAuth Client: 1. Open the client you created. 2. Turn off **Use default logout/callback URLs and Origins**. 3. Add the callback URL using the port configured in CoCo's `redirect_port`. For example: ``` http://localhost:8585 ``` Make sure the port in the callback URL matches the `redirect_port` you configure in CoCo. #### **3. Connect the MCP Server** Configure the CARTO MCP Server in CoCo using the **MCP Server URL** and the **SPA OAuth Client ID**: ``` { "oauth": { "client_id": "", "redirect_port": 8585, "scope": "openid profile email read:workflows write:workflows" }} ``` #### **4. Sign in to CARTO** The first time CoCo connects to the CARTO MCP Server, it opens a browser window. Sign in to CARTO to authorize the connection. Once authentication is complete, CoCo can use the CARTO tools available through MCP. {% hint style="info" %} If sign-in fails with a callback error, check the `redirect_uri` parameter in the authorization URL in your browser. This shows the exact callback URL CoCo is using, which must be registered on the SPA OAuth Client. {% endhint %} See [Connecting with OAuth](/carto-for-agents/mcp-server/connecting-with-oauth) for the shared OAuth mechanics. ## CARTO CLI The CoCo CLI runs in a terminal, so the [CARTO CLI](/carto-for-agents/cli) can be used alongside MCP and Agent Skills for scripting, automation, and administration. Install the CLI: ``` npm install -g @carto/carto-cli ``` Authenticate: ``` carto auth login ``` The CLI is useful when a task is better suited to command-line operations, scripting, or CARTO administration than to an MCP tool call. ## Agent Skills [CARTO Agent Skills](/carto-for-agents/agent-skills) complement MCP and the CLI. They provide CARTO-specific instructions and workflows that help CoCo use both interfaces consistently and idiomatically. CoCo reads skills from several locations, including `.claude/skills/` in a project and `~/.claude/skills/` for a user, alongside its own `.cortex/skills/` and `~/.snowflake/cortex/skills/`. Each skill is a folder containing a `SKILL.md` file with YAML frontmatter. If you have already installed the CARTO Agent Skills for another coding agent that uses `~/.claude/skills/`, CoCo picks them up with no further setup. Otherwise, see [**Agent Skills → Installation**](/carto-for-agents/agent-skills/installation). MCP provides CoCo with access to CARTO tools, while the CLI provides command-line capabilities. Skills provide the guidance for using them effectively. # Databricks Genie Code [Databricks](https://docs.databricks.com/aws/en/generative-ai/mcp) connects to CARTO as an **MCP service** – a Unity Catalog securable accessed through the Unity AI Gateway. The Unity AI Gateway provides governance controls for MCP connections, including permissions, tool selection, rate limits, usage tracking, and auditing. Today, the best way to leverage CARTO's MCP Server from within Databricks is by using [Genie Code](https://docs.databricks.com/aws/en/genie-code/).

## Requirements Before you start, you need: * A **Unity Catalog-enabled** Databricks workspace in a region that supports **Model Serving**. * `CREATE CONNECTION` on the target schema. **Metastore admin access is not required.** * Your CARTO **MCP Server URL**. * Credentials for the CARTO MCP Server: * **OAuth (U2M):** recommended for access to the full CARTO tool surface. * **Bearer token:** sing a CARTO API Access Token for the [read-and-discovery subset](/carto-for-agents/mcp-server/connecting-with-api-tokens#what-a-token-unlocks). ## Install The MCP server is registered through the Databricks UI or REST API. To do it from the UI, you should go to the AI Gateway section of the AI/ML module. ### 1. Create a CARTO SPA OAuth Client If you're using create a **SPA OAuth Client** in CARTO under **Developers > Credentials > SPA OAuth Clients**. * Configure the client as **confidential** so that it has a **Client Secret**. * Keep the **Client ID** and **Client Secret**. You'll enter these when configuring the Databricks MCP service. Before creating the connection, add the Databricks workspace callback URL to the client's **Allowed Callback URLs**: ``` https:///login/oauth/http.html ``` The callback is **workspace-specific**, so each Databricks workspace requires its own entry. ### 2. Create the MCP Service In Databricks, go to: **AI Gateway > MCPs** Select: **+ MCP > Connect an existing MCP server**

Configure the MCP service: 1. Select a **Catalog** and **Schema**. Use the actual catalog and schema where you want to register the MCP service. The form may prefill `main` and `default`, which may not exist in your workspace. 2. Enter a **Name**, for example: ``` carto_mcp ``` 3. Enter your CARTO **MCP Server URL**. 4. Select an **Authentication** method. **OAuth (U2M)** Use **OAuth (U2M)** for the full CARTO tool surface. Enter: * **Client ID:** your CARTO SPA OAuth Client ID. * **Client Secret:** your CARTO SPA OAuth Client Secret. * **Authorization endpoint:** `https://auth.carto.com/authorize` * **Token endpoint:** `https://auth.carto.com/oauth/token` Make sure the Databricks workspace callback URL has been added to the CARTO client's **Allowed Callback URLs** before connecting.

**Bearer token** Use **Bearer token** for the read-and-discovery path. Enter your CARTO **API Access Token**. Databricks proxies the MCP calls, so the token is not exposed to end users. The available capabilities depend on the APIs included in the token. The read-and-discovery subset includes browsing connections, running SQL, and searching the Data Observatory.

{% hint style="warning" %} Don't select **Dynamic Client Registration**. CARTO does not use DCR. Use **OAuth (U2M)** or **Bearer token**. {% endhint %}

### 3. Load and configure the tools Select **Create & load tools**. Databricks discovers the tools exposed by the CARTO MCP server and displays them with **Read-only** or **Destructive** badges. Under **Advanced**, you can filter the tools using globs, for example: ``` read_*list_* ``` Use the filter to expose only the CARTO tools required by your application.

### 4. Create the MCP Service Create the service. Once provisioning is complete, the MCP service status changes to **Active**. {% hint style="info" %} **Tool caps are surface-specific.** Databricks' **Genie Code** caps an agent at 20 tools across all servers – but with a per-tool picker, so you choose which of CARTO's tools to expose. The **AI Playground** has no such cap. Use the glob filter to keep a focused set and to exclude `view_map` (which can't render inline here). {% endhint %}

## Governance Databricks lets you go beyond a connection: * **Tool selection:** expose only the tools you want (allowlist by prefix or exact match). * **Service policies:** allow, deny, or require approval for individual tool calls. The Destructive badge is informational; set a policy to actually gate destructive tools. * **Rate limits** and **usage tracking**: every call lands in `system.ai_gateway.usage`. ## Add the CARTO Agent Skills [CARTO Agent Skills](https://docs.carto.com/carto-for-agents/agent-skills) are playbooks that teach the agent how to use the CARTO tools well: which tool to reach for, the right SQL dialect per warehouse, and recipes for common spatial analyses. Today, only Databricks Genie Code supports the simultaneous use of both 3rd party MCP Server connections and Agent Skills. In order to be able to leverage CARTO Agent Skills with Genie Code, you should first load them into your Databricks Workspace: 1. Go to your Workspace, and locate the folder `.assistant`

2. Create the folder Skills 3. Inside that folder, import CARTO Agent Skills. You can download the carto-skills-all.zip from [here](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-skills-all.zip).

## Customise Databricks Genie Code We are now going to connect CARTO's MCP Server to Genie Code, and we'll also make available the Agent Skills that we have previously uploaded to our Databricks Workspace. 1. Open Genie Code, and go to the "Customizations" section

2. In order to connect first the MCP Server, go into "Connectors" and click to "Add MCP server". 3. In section **UC MCP Service** you should select the MCP Service that connects to CARTO MCP Server that has been previously created. Then click on the "Save" button.

4\. Enable the UC MCP Service connector and click to "Configure tools".

5. Select which tools from CARTO's MCP Server are more relevant for your tasks. Note that you can always enable and disable tools based on what you are going to be asking Genie Code to do.

6. Now go to the section "Skills" on the Genie Code Customizations panel. There you should click to `"Add skill"`, and select the folder in your Workspace where you have added the CARTO Agent Skills previously.

7. Enable the Agent Skills that are relevant for your tasks, and there you go! You are ready to use Databricks Genie Code with CARTO's MCP Server and Agent Skills.

# Oracle (OCI Generative AI) [Oracle Cloud Infrastructure (OCI)](https://docs.oracle.com/en-us/iaas/Content/generative-ai/mcp.htm?utm_source=chatgpt.com) can call CARTO's MCP Server through **MCP Calling** on the OpenAI-compatible **Responses API** using Streamable HTTP. MCP Calling is generally available (GA) on OCI Generative AI. This is a **code-based integration** and requires an OCI administrator to configure the necessary IAM policies. {% hint style="warning" %} OCI Generative AI **Agents**, the service marketed as **Agent Factory**, cannot host **Agent Factory is not the MCP integration path.** OCI Generative AI **Agents**, the service marketed as **Agent Factory**, cannot host an MCP server and does not provide an MCP tool type. Its available tool types include RAG, SQL, function calling, HTTP endpoints, and agent tools. CARTO MCP is connected through **OCI Generative AI's Responses API**, using MCP Calling. {% endhint %} ## Authentication **Oracle uses a token-based connection for MCP Calling.** OCI passes a pre-obtained bearer token to the MCP server and does not run an interactive OAuth flow\.As a result, the CARTO connection uses a **CARTO API Access Token**. With the required token configuration, the integration provides access to the **read and discovery** subset of CARTO capabilities: * Browsing connections * Running SQL * Searching the Data Observatory For the broader set of CARTO tools, add the **SQL, Maps, and LDS APIs** to the token. The following capabilities require OAuth and are therefore not available through this OCI integration: * Starting a Workflow run * Map authoring * Workflow authoring * Administrative operations ## Requirements Before you start, you need: * A tenancy in a region that supports agentic features. In EMEA, supported regions include **Frankfurt, London, and Riyadh**. * An **OCI administrator** who can create the required IAM policy. * A developer comfortable with **Python**. * Your CARTO **MCP Server URL**. * A CARTO **API Access Token** with the **MCP Server** scope. ## Install ### 1. Configure the IAM policy An OCI administrator must grant your group permission to use the Generative AI service. The `generative-ai-family` aggregate resource covers both inference and API-key operations. Run the following as an administrator: ``` allow group to manage generative-ai-family in compartment ``` See [Oracle's IAM policy documentation](https://docs.oracle.com/en-us/iaas/Content/Identity/Concepts/policyoverview.htm) for more information. ### 2. Point the OpenAI SDK at Oracle OCI Generative AI provides an OpenAI-compatible API, so you can use the OpenAI Python SDK by pointing the client at the OCI endpoint: ```python from openai import OpenAI client = OpenAI( base_url="https://inference.generativeai..oci.oraclecloud.com/openai/v1", api_key="", project="", ) ``` Replace `` and `` with your OCI values. See [Oracle's OpenAI compatibility documentation](https://docs.oracle.com/en-us/iaas/Content/generative-ai/developer-tutorials/using-openai-compatible-apis.htm) for more information. ### 3. Declare CARTO as an MCP tool Pass the CARTO MCP Server as an MCP tool in the Responses API request: ```python resp = client.responses.create( model="", input="What CARTO connections do I have?", tools=[{ "type": "mcp", "server_label": "carto", "server_url": "https://.api.carto.com/mcp/", "authorization": "", "require_approval": "never", "allowed_tools": ["explore_data", "search_data_observatory"], }], ) ``` See [Oracle's MCP Calling documentation](https://docs.oracle.com/en-us/iaas/Content/generative-ai/mcp.htm?utm_source=chatgpt.com) for the complete MCP configuration and Responses API syntax. {% hint style="info" %} Two details: the token goes in `authorization` **without the `Bearer` prefix** (OCI adds it), and `require_approval` controls whether the agent pauses before running a tool — set it deliberately. Use `allowed_tools` to expose a focused, low-risk set and to suppress `view_map`, which can't render inline here. {% endhint %} # CARTO MCP Server The CARTO MCP Server is the fastest way to put the CARTO platform inside your AI assistant. Through the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), agents like Claude, ChatGPT, Gemini Enterprise, and Microsoft Copilot Studio can work with your CARTO account directly in the conversation: explore connected data warehouses, create and edit Builder maps, author and run Workflows, render maps inline, and reach organization admin — all in natural language, over a single URL. The AI model runs in your assistant. CARTO receives the tool calls the assistant makes and returns their results, and never sees your conversation.

## What your agent can do Once connected, your agent has a broad set of CARTO tools available. It picks the right one from your natural-language request — you don't need to know tool names.

Capability	What the agent can do
Explore data	List connections, browse and search warehouse tables, inspect column distributions, and locate named sources and saved maps.
Create & edit maps	Build a Builder map from a table or SQL query, restyle layers, add widgets and popups, set privacy, and open the result — reading and updating existing maps in place.
Build & run workflows	Author an analytical workflow (filter, spatial join, group-by, enrich), validate it, run it in sync or async mode, and schedule it.
Query & analyze	Run spatial SQL, geocode addresses, compute isolines and routes, and enrich with the Data Observatory.
Import & export	Bring geospatial files into the warehouse, export results back out, and move data between connections.
Manage your workspace	Work with connections, credentials, named sources, and projects — and, for admins, users, org settings, and activity data.

Full per-tool documentation is in the [MCP Tools Reference](/carto-for-agents/mcp-server/tools-reference). Your team extends this catalog by [publishing any Workflow as an MCP tool](/carto-user-manual/workflows/workflows-as-mcp-tools). {% hint style="info" %} Interactive maps render inline only in MCP clients that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview#client-support) — Claude.ai, ChatGPT, and Claude Desktop today. In clients that don't, the map tool returns a text confirmation; ask the agent for the map URL and open it in CARTO instead. {% endhint %} ## Get your MCP Server URL Find the **MCP Server URL** in your CARTO Workspace. Editors and Admins have it under **Developers > Workflow API & MCP Server**; everyone except Guests also has it under **Settings > CARTO AI > CARTO MCP Server**. It follows this pattern: ``` https://.api.carto.com/mcp/ ``` If your organization signs in to CARTO through single sign-on (SSO), use the separate **SSO login** URL shown below the standard one. It routes the interactive login through your identity provider, so members authenticate with their SSO credentials: ``` https://.api.carto.com/mcp/sso/ ```

The Workflow API & MCP Server page in CARTO Workspace, showing the Standard login and SSO login MCP Server URLs

{% hint style="warning" %} Copy the URL from the Workspace rather than assembling it by hand — this is the most common setup mistake. On **self-hosted and dedicated** deployments the path is `https:///api/mcp/` (note the `/api/` prefix); a wrong path returns a bare `405 Not Allowed`. On these deployments the MCP Server is part of your own installation, so the whole path from your agent to your warehouse stays inside your boundary. {% endhint %} ## Choose how to authenticate How you authenticate decides how much of CARTO your agent can use. This is the most important setup decision.

Method	Best for	What the agent gets
OAuth (U2M)	Interactive clients — Claude, ChatGPT, Gemini, Copilot, Snowflake, Databricks	The tools your role allows: for Editors and Admins that includes creating and editing maps and authoring workflows; admin tools appear for Admins. Each person signs in as themselves. See which tools each role sees.
OAuth (M2M)	Unattended, service-to-service access	The full surface, with no interactive login, via an M2M OAuth client.
API Access Token	Quick read-and-discovery setups, and hosts that only accept a static token (Oracle)	A read-and-discovery subset that depends on the token's Allowed APIs — browse data, run SQL, poll (not start) Workflow runs, search the Data Observatory. No map or Workflow authoring, no admin.

{% hint style="success" %} **Rule of thumb:** if the agent should *do* things — build maps, author workflows, administer the org — use **OAuth**. If it only needs to *look at* things, an **API Access Token** is a quick start. {% endhint %} Whichever you choose, the agent can do exactly what you can do in CARTO. Everything it does is recorded in your organization's [Activity Data](/carto-user-manual/settings/activity-data) and counts towards your [usage quota](/carto-user-manual/settings/quotas-and-rate-limits/understanding-your-organization-quotas) like any other use of the CARTO APIs. **Claude and Claude Code connect with just the URL** — no OAuth client to create, nothing to register. Other clients use a self-service SPA OAuth client. See [Connecting with OAuth](/carto-for-agents/mcp-server/connecting-with-oauth). {% hint style="success" %} For step-by-step setup on your platform — Claude, ChatGPT, Copilot, Gemini, Snowflake, Databricks, Oracle, and coding agents — see [Connect your platform](/carto-for-agents/connect-your-platform). {% endhint %} *** ## Available tools The CARTO MCP Server ships with a catalog of built-in tools, organized by category. Your team adds to it by publishing Workflows as MCP tools. Full per-tool documentation, including every parameter, is in the [MCP Tools Reference](/carto-for-agents/mcp-server/tools-reference).

Category	What it covers
Maps tools	Create, update, validate, read, and render Builder maps.
Workflow tools	Create, run, schedule, and inspect Workflows, plus any your team publishes as MCP tools.
Data tools	Explore connections and tables, run SQL, geocode, route, import/export, and enrich with the Data Observatory.
Workspace tools	Manage users, credentials, projects, and activity data.

{% hint style="info" %} CARTO is expanding the MCP surface over time. If there's a platform capability you'd like exposed as a tool, [get in touch](https://carto.com/contact). {% endhint %} # Connecting with OAuth OAuth is the recommended way to connect. It gives your agent **every tool your role allows** — for Editors and Admins that means creating and editing maps, building and running Workflows, and more — and signs each person in as themselves, so CARTO logs the real user. How much setup you do depends on your client. Some connect with nothing but the URL. Others need a one-time OAuth client you create in CARTO. Both paths are below. {% hint style="info" %} Looking for setup steps for a specific platform? See [Connect your platform](/carto-for-agents/connect-your-platform). This page explains the shared OAuth mechanics behind those guides. {% endhint %} ## The simplest path: clients that support CIMD Some clients register themselves with CARTO automatically through a **Client ID Metadata Document (CIMD)**, so there's nothing to create — no OAuth client, no secret, no callback to register. Today CARTO recognizes CIMD for **Claude.ai, Claude Desktop, and Claude Code**; other clients (ChatGPT, Copilot Studio, Gemini, and the rest) take the one-time-client path below. For a CIMD client: 1. Copy your **MCP Server URL** from **Developers > Workflow API & MCP Server**. 2. Add it as an MCP server in the client. 3. When prompted, log in to CARTO to authorize. That's it. See the [Claude guide](/carto-for-agents/connect-your-platform/claude) for the exact clicks. {% hint style="info" %} CIMD is a client capability, not a CARTO setting. If a non-Claude client offers a "dynamic registration" or "CIMD" option, it will fail against CARTO today — choose the manual **User-Defined OAuth Client** option and follow the steps below instead. {% endhint %} ## Everything else: a one-time OAuth client Other clients — ChatGPT, Copilot Studio, Gemini, Snowflake, Databricks, and more — connect with a **SPA OAuth client** you create once in CARTO. It's self-service; you don't need a CARTO ticket. There are three short steps. ### 1. Create the client in CARTO In **Developers > Credentials**, open the **SPA OAuth Clients** tab and click **Create new > SPA OAuth Client**. Give it a name, then copy its **Client ID** and **Client Secret**. ### 2. Enter the OAuth settings in your client In your AI platform's MCP setup, choose OAuth and fill in these values: | Field | Value | | ------------------ | ----------------------------------------------------- | | MCP Server URL | from **Developers > Workflow API & MCP Server** | | Client ID / Secret | from step 1 | | Authorization URL | `https://auth.carto.com/authorize` | | Token URL | `https://auth.carto.com/oauth/token` | | Scopes | `openid profile email read:workflows write:workflows` | ### 3. Register the callback URL back in CARTO Your client will show you a **redirect (callback) URL** — usually only after you've saved the OAuth settings. Copy it, return to your SPA client in CARTO, turn off **"Use default logout/callback URLs and Origins"**, and paste it into **Allowed Callback URLs**. Save, then finish signing in. That last step is the one people miss. If sign-in fails with **"Callback URL mismatch,"** the URL isn't registered, or doesn't match exactly (no wildcards). {% hint style="success" %} The per-platform guides give you each client's exact callback URL and any quirks, so you don't have to hunt for it. Start there: [Connect your platform](/carto-for-agents/connect-your-platform). {% endhint %}

Callback URLs for common clients

| Client | Callback URL | | ----------------- | ------------------------------------------------------------------------------------------------------------------- | | ChatGPT | `https://chatgpt.com/connector/oauth/` (read `` from the authorize URL) | | Snowflake | `https://identity.snowflake.com/oauth2/callback` (fixed — register up front) | | Gemini Enterprise | `https://vertexaisearch.cloud.google.com/oauth-redirect` (fixed — use it as the SPA client's Application Login URL) | | Databricks | `https:///login/oauth/http.html` (per workspace) | | MCP Inspector | `http://localhost:8000/callback` | | MCP Jam | `http://127.0.0.1:6274/oauth/callback/debug`, `http://127.0.0.1:6274/oauth/callback` | The field accepts a comma-separated list, so one client can serve several platforms.

## What signing in grants You authorize the platform to use the CARTO MCP Server on your behalf — exploring your data, creating and editing maps, running your Workflows, and (with the right permissions) reaching workspace and admin tools. The token inherits your own CARTO permissions, so the agent reaches the connections, datasets, and maps your account can access. Your agent can do exactly what you can do in CARTO, so if you're an Admin it can use admin tools too. If a connection [requires viewer credentials](/carto-user-manual/connections/sharing-a-connection#requiring-viewer-credentials-on-shared-connections), the agent's queries run under your own warehouse identity as well, so your warehouse's audit log attributes them to you. Revoke it any time from **Developers > Credentials > SPA OAuth Clients**, or from your platform's connector settings. ## SSO and self-hosted * **SSO.** If your organization signs in to CARTO through single sign-on, copy the **SSO login** URL from **Developers > Workflow API & MCP Server** instead of the standard one, so login routes through your identity provider. * **Dedicated or self-hosted.** Swap `auth.carto.com` for your own auth domain. You can confirm it at `https:///.well-known/oauth-protected-resource/api/mcp/`. ## Unattended access (M2M) For service-to-service access with no interactive login, use a **machine-to-machine OAuth client**: 1. In **Developers > Credentials**, open the **M2M OAuth Clients** tab. 2. Click **Create new > M2M OAuth Client**, name it, and save. 3. Open it, copy its **Client ID** and **Client Secret**, and configure your client with those plus the MCP Server URL. See [M2M OAuth Clients](/carto-user-manual/developers/managing-credentials/m2m-oauth-clients) for details. ## Troubleshooting * **"Callback URL mismatch"** — the redirect URL isn't registered on your SPA client, or doesn't match exactly. Recheck [step 3](#3-register-the-callback-url-back-in-carto). * **"Unknown client"** — the Client ID doesn't resolve. Create a fresh SPA OAuth client and use its ID. * **"Dynamic client registration is disabled"** — the client tried to register itself automatically. Choose the **Manual** / **User-Defined OAuth Client** option and enter your values by hand. * **No tools after connecting** — confirm you connected over OAuth (not a token), and that any published Workflows have synced. * **Permission errors** — the token inherits the signed-in user's permissions. Make sure that user can access the relevant connections and Workflows. For token-based connections instead, see [Connecting with API Access Tokens](/carto-for-agents/mcp-server/connecting-with-api-tokens). # Connecting with API Access Tokens An API Access Token is the quickest way to connect an agent for **read and discovery** work — browsing connections, querying data, and searching the Data Observatory. It's also the only option on hosts that don't run an interactive OAuth flow (such as Oracle OCI). You create a token in CARTO Workspace, then pass it as an authorization header when registering the MCP Server in your agent. {% hint style="info" %} A token session reaches a **read-and-discovery subset** of the tools — it can't create or edit maps, author Workflows, or reach admin. For the full surface, use [OAuth](/carto-for-agents/mcp-server/connecting-with-oauth). {% endhint %} {% hint style="warning" %} **The token's Allowed APIs decide which tools appear** — and the MCP Server scope alone unlocks only four. See [What a token unlocks](#what-a-token-unlocks) below before you create the token; the difference between four tools and fourteen is which data APIs you add. {% endhint %} ## Step 1: Create an API Access Token The MCP Server requires authentication via an [API Access Token](/carto-user-manual/developers/managing-credentials/api-access-tokens): 1. In CARTO Workspace, [create a new token](/carto-user-manual/developers/managing-credentials/api-access-tokens#creating-an-api-access-token). 2. In **Allowed APIs**, switch on the **MCP Server** scope — this admits the token to the server. Then add the data APIs the agent actually needs: **SQL** to query at all, **Maps** for table stats (`describe`), **LDS** for geocoding and routing, **Imports/Exports** to load and export data. See [What a token unlocks](#what-a-token-unlocks) — the MCP Server scope on its own reaches only four tools. 3. Under **Grants**, add at least one grant naming a connection. 4. Optionally, set an **expiration date**. Tokens don't expire unless you set one, so pick a date that matches how long the agent needs access. You can revoke a token at any time by deleting it. 5. Copy the token securely, using the copy button — you'll need it to connect the agent.

{% hint style="warning" %} **Get the SQL grant `source` right, or queries will fail.** A grant is a `{connection, source}` pair, and what `source` must contain depends on the API: * For the **SQL API** (`execute_query`), `source` must be the **query text itself**, or `*` for any query — *not* a table name. A table-scoped grant returns `403` for a `SELECT` against that table. * For **map and table reads**, `source` is a fully-qualified table name. For an agent that composes its own SQL, granting `*` is usually the practical choice. {% endhint %} ## What a token unlocks Which tools a token session sees depends entirely on its **Allowed APIs**. The MCP Server scope is only the admission ticket — on its own it reaches **four tools**. Each additional data API adds more: | Allowed API | Tools it unlocks | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **MCP Server** (alone) | `explore_data` (list connections, browse and search resources — **not** `describe`), `search_data_observatory`, `validate_map`, `validate_workflow`. Four tools. | | **+ SQL** | `execute_query` and `execute_async_query` (the agent can't query at all without this), plus `run_workflow` **status only** — it can poll a run, but starting one and fetching results needs OAuth. | | **+ Maps** | `describe` on `explore_data` — table and column statistics, which data-aware map styling depends on. | | **+ LDS** | `geocode`, `route`, `calculate_isolines`, `calculate_od_matrix`. | | **+ Imports / Exports** | `import_data`, `export_data`, `transfer_data`. | With SQL, Maps, LDS, Imports and Exports all enabled, a token reaches **fourteen tools**. Everything beyond that — creating and editing maps, authoring and running Workflows, connections, and admin — is [OAuth](/carto-for-agents/mcp-server/connecting-with-oauth) only. {% hint style="info" %} A read-and-discovery token can still change data. `execute_query` and `execute_async_query` run any statement the connection's database user is allowed to run, including ones that modify data. Grants decide which tables the agent can reach, and the connection's database user decides what it can do to them. For an agent that should only read, point the token at a connection whose database user has SELECT permission only. {% endhint %} ## Step 2: Add the MCP Server to your agent Use the **MCP Server URL** (from the [overview page](/carto-for-agents/mcp-server#get-your-mcp-server-url)) and the API Access Token to register the server. The exact command varies by agent — most take a URL, a transport, and an `Authorization: Bearer ` header. For example, with Gemini CLI: ```bash gemini mcp add carto \ https://.api.carto.com/mcp/ \ -H 'Authorization: Bearer ' \ -t http ``` * Replace `` and `` with the values from your MCP Server URL (copy the full URL from **Developers > Workflow API & MCP Server**). * `-t http` sets the transport protocol (Streamable HTTP). * The `Authorization` header carries the API Access Token from Step 1. After setup, the agent can browse your connections, inspect tables, run SQL, and search the Data Observatory in response to your questions — the exact set depends on the token's Allowed APIs (see [What a token unlocks](#what-a-token-unlocks)). Running a saved Workflow end to end needs OAuth. # MCP Tools Reference The CARTO MCP Server exposes a catalog of built-in tools an agent calls to explore data, work with maps and Workflows, and administer your organization. Related operations are grouped into a single tool that takes a discriminator parameter — for example, `explore_data` handles listing connections, browsing tables, searching, and describing columns through one `method` argument. This keeps the catalog compact so it fits comfortably inside every host's tool limit. You don't call these tools by hand. Your agent picks the right tool and parameters from your natural-language request; this reference is here so you understand what the agent can do and can reason about its actions. ## Categories

Category	What it covers
Maps tools	Create, update, validate, read, and render Builder maps.
Workflow tools	Create, run, schedule, and inspect Workflows, plus any your team publishes as MCP tools.
Data tools	Explore connections and tables, run SQL, geocode, route, import/export, and enrich with the Data Observatory.
Workspace tools	Manage users, connections, credentials, projects, customizations, and activity data.

## How the tools are described Each tool entry lists: * **What it does** and when the agent uses it. * Its **method** (or `operation` / `kind`) parameter, if it groups several operations, with the available values. * The **key parameters** the agent supplies. Full parameter details — including optional fields and provider-specific options — live in each tool's own MCP description, which the agent reads at call time. * Whether the tool is **read-only** or can **modify or delete** data. CARTO annotates every tool so hosts that ask for confirmation before destructive actions can do so. ## Which tools an agent can use Which tools an agent sees is decided at three layers: 1. **How it authenticated.** Over an [API Access Token](/carto-for-agents/mcp-server/connecting-with-api-tokens), the agent gets a read-and-discovery subset that grows with the token's Allowed APIs, such as browsing data, running SQL, polling Workflow runs and searching the Data Observatory. Authoring and admin tools aren't offered. See [What a token unlocks](/carto-for-agents/mcp-server/connecting-with-api-tokens#what-a-token-unlocks) for the exact breakdown. Over [OAuth](/carto-for-agents/mcp-server/connecting-with-oauth), the agent sees the tools the signed-in user's role allows; the table below shows which. 2. **What your team publishes.** Your team decides which Workflows become MCP tools and what inputs each accepts. See [How published tools are governed](/carto-for-agents/mcp-server/tools-reference/workflow-tools#how-published-tools-are-governed). 3. **Your MCP client.** Most clients let an administrator enable or disable individual tools per connected server, on your side. The model reads each tool's description to decide when to call it. Built-in descriptions ship with CARTO releases; Workflow-tool descriptions are written by your own editors when they publish. ### What each role sees over OAuth Tools are grouped, so a tool with several methods may appear with fewer of them for a given role, and disappears when none are left.

Tool	Admin	Editor	Viewer
Maps
`create_map`, `update_map`	✓	✓	–
`read_maps`, `validate_map`, `view_map`	✓	✓	✓
Workflows
`create_workflow`, `update_workflow`, `schedule_workflow`	✓	✓	–
`read_workflows`, `validate_workflow`, `read_workflow_components`	✓	✓	✓
`run_workflow`	✓	✓	`status` and `results` only
Your published Workflow tools	✓	✓	✓
Data
`manage_connections`, `import_data`, `transfer_data`	✓	✓	–
`explore_data`, `execute_query`, `execute_async_query`, `export_data`	✓	✓	✓
`geocode`, `route`, `calculate_isolines`, `calculate_od_matrix`	✓	✓	✓
`search_data_observatory`	✓	✓	✓
`manage_named_sources`	✓	✓	–
`manage_data_observatory_subscriptions`	✓	no `unsubscribe`	no `unsubscribe`
Workspace
`manage_api_access_tokens`	✓	✓	–
`manage_oauth_clients`, `organize_projects`	✓	✓	read only
`manage_users`	✓	`list` only	`list` only
`admin_carto`	✓	read only	read only
`admin_carto_customizations`	✓	read only	read only
`export_activity_data`	✓	–	–
`delete`	✓	✓	–
`get_workspace_info`	✓	✓	✓

Superadmin-only tools ([`superadmin_carto_resources`](/carto-for-agents/mcp-server/tools-reference/workspace-tools#superadmin_carto_resources)) aren't offered to Admins. This table shows what the agent is offered; each call is still checked against your CARTO permissions when it runs. ## Extend the catalog with your own Workflows Any Workflow your organization builds can be published as an MCP tool, registering alongside the built-in tools. See [Workflow tools](/carto-for-agents/mcp-server/tools-reference/workflow-tools#your-published-workflows) and [Workflows as MCP Tools](/carto-user-manual/workflows/workflows-as-mcp-tools). # Maps tools Maps tools let your agent create Builder maps from your data, edit them in place, validate them before saving, find existing maps, and render a map inline in the conversation.

## `create_map` **Title:** Create Map **Creates a new Builder map** from a full map definition. The agent runs the complete pipeline — offline validation, SQL-parameter planning, and dataset creation and verification — so the map is ready to open. To change an existing map, the agent uses [`update_map`](#update_map). | Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bundle` | object | Yes | The map definition: datasets (SQL or table sources plus a connection), layers, widgets, basemap, privacy, and optional agent config. Layers link to datasets by reference. | *Can modify data: creates a new map.* ## `update_map` **Title:** Update Map **Changes an existing map.** Applies a partial update, patches a single dataset, or publishes the saved state. Fields you don't mention are preserved. **Method:** `update` · `update_dataset` · `publish` | Parameter | Type | Required | Description | | --------------------- | -------------------- | -------------------- | --------------------------------------------------------------------- | | `id` | string | Yes | The map to update. | | `bundle` | object | For `update` | A partial bundle; unmentioned fields are kept. | | `datasetsMode` | `merge` \| `replace` | No | `merge` (default) keeps unmentioned datasets; `replace` removes them. | | `dryRun` | boolean | No | Preview the change without writing. | | `datasetId` / `patch` | string / object | For `update_dataset` | The dataset to patch and the fields to change. | *Can modify data.* ## `validate_map` **Title:** Validate Map **Checks a map definition without creating or changing anything.** `validate` runs offline structural and type checks; `verify` additionally dry-runs each dataset's SQL against the warehouse. **Method:** `validate` · `verify` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------ | | `bundle` | object | Yes | The map bundle to check. | *Read-only.* ## `read_maps` **Title:** Browse Maps **Finds and inspects saved maps.** Lists maps with search and paging, gets one map's full definition, or lists a map's datasets. **Method:** `list` · `get` · `list_datasets` | Parameter | Type | Required | Description | | -------------------- | ------- | -------------------------- | ------------------------------------------------- | | `id` | string | For `get`, `list_datasets` | The map to read. | | `search` | string | No | Free-text name search (for `list`). | | `page` / `page_size` | number | No | Paging for `list` (default 20, max 100 per page). | | `mine_only` | boolean | No | Only maps you own. | *Read-only.* ## `view_map` **Title:** View Map **Renders an interactive map inline in the chat.** Two modes: pass a `@deck.gl/json` spec the agent generates for an ad-hoc visualization, or a `mapId` to open a saved Builder map. The agent composes the spec from your request over any table or SQL query — you don't write it yourself. | Parameter | Type | Required | Description | | ------------- | ------ | -------------- | --------------------------------------------- | | `deckglProps` | object | One of the two | A deck.gl declarative spec for an ad-hoc map. | | `mapId` | string | One of the two | The UUID of a saved Builder map you can read. | *Read-only.* {% hint style="info" %} `view_map` renders inline only on hosts that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview#client-support) — Claude.ai, ChatGPT, and Claude Desktop. On other hosts it returns a text confirmation; ask the agent for the map URL and open it in CARTO. {% endhint %} ### Previewing a saved Builder map With a `mapId`, `view_map` shows a lightweight, read-only preview of the saved map. It renders the layers with their styling, the basemap, the saved viewport, popups, and the legend. You can pan, zoom, open popups, and turn layers on and off. Some Builder features are only available in Builder itself. The table below shows how the preview handles them. | Builder feature | In the preview | | -------------------------------- | ---------------------------------------------------------------------------- | | Widgets | Widgets are hidden, and the layers show all their data. | | SQL parameters | The parameter controls are hidden. Layers use the values saved with the map. | | Custom markers | Custom marker icons appear only in Builder. | | Google Maps and custom basemaps | The preview uses the closest CARTO basemap. Positron is the default. | | AI Agents | The map's agent is available in Builder. | | Map description and other panels | Only the map title, legend, and zoom controls are shown. | To see the complete map, use the link in the preview header to open it in CARTO. # Workflow tools Workflow tools let your agent author analytical Workflows (DAGs of components), validate and compile them, run them in sync or async mode, schedule them, and inspect the component catalog. They also cover the Workflows your team publishes as reusable MCP tools.

## `create_workflow` **Title:** Create Workflow **Creates a new Workflow** from a full definition. The agent validates the DAG's components and parameters against the connection before creating it. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------------------------------------------------------------------------------- | | `bundle` | object | Yes | The Workflow definition: title, connection, privacy, and a `config` with nodes and edges. | | `connection` | string | No | Connection to validate against, overriding the bundle's. | *Can modify data: creates a new Workflow.* ## `update_workflow` **Title:** Update Workflow **Changes an existing Workflow**, sets sharing, or publishes it as a callable MCP tool. **Method:** `update` · `share` · `unshare` · `publish` · `unpublish` | Parameter | Type | Required | Description | | ---------------------------- | ------------------------- | ---------------------- | --------------------------------------------------- | | `id` | string | Yes | The Workflow to change. | | `bundle` | object | For `update` | A partial definition; unmentioned fields are kept. | | `org` / `emails` / `canEdit` | boolean / array / boolean | For `share`, `unshare` | Who to share with, and whether they can edit. | | `name` / `description` | string | For `publish` | Override the published tool's name and description. | *Can modify data.* ## `schedule_workflow` **Title:** Schedule Workflow **Adds, replaces, or removes a Workflow's schedule.** Compiles the DAG to SQL and registers a warehouse cron. **Method:** `add` · `update` · `remove` | Parameter | Type | Required | Description | | ------------ | ------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `id` | string | Yes | The Workflow to schedule. | | `expression` | string | For `add`, `update` | The schedule expression (provider-specific: BigQuery natural language; Snowflake, Postgres, Redshift cron; Databricks Quartz). | *Can modify data.* ## `validate_workflow` **Title:** Validate Workflow **Checks a Workflow without creating or running it.** Validates structure and components, deep-verifies against the live connection, or compiles the DAG to SQL for inspection. **Method:** `validate` · `verify` · `to_sql` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------- | | `bundle` | object | Yes | The Workflow definition to check. | | `connection` | string | No | Connection to validate against, overriding the bundle's. | *Read-only.* ## `read_workflows` **Title:** Browse Workflows **Finds and inspects Workflows** and the Workflows published as MCP tools. **Method:** `list` · `get` · `list_mcp_tools` · `get_mcp_tool` | Parameter | Type | Required | Description | | --------- | ------ | ------------------------- | ------------------------------------ | | `id` | string | For `get`, `get_mcp_tool` | The Workflow to read. | | `search` | string | No | Title substring search (for `list`). | *Read-only.* ## `run_workflow` **Title:** Run Workflow **Runs a Workflow and collects its output.** Compiles the DAG to SQL, submits it, reports status, and fetches result rows. **Method:** `run` · `status` · `results` {% hint style="info" %} Over a [token session](/carto-for-agents/mcp-server/connecting-with-api-tokens#what-a-token-unlocks), only `status` is available (with the **SQL** API on the token) — the agent can poll a run it did not start. Starting a run (`run`) and fetching `results` need OAuth. {% endhint %} | Parameter | Type | Required | Description | | ---------------------- | ------ | -------------------- | -------------------------------------------------------------- | | `id` | string | For `run`, `results` | The Workflow to run. | | `connection` / `jobId` | string | For `status` | The connection the run was submitted on, and the job to check. | | `node` | string | For `results` | Which node's output to return. | | `limit` | number | No | Max rows to return (default 100). | *Can modify data: a run executes the compiled SQL.* ## `read_workflow_components` **Title:** Browse Workflow Components **Lists the available Workflow components** on a connection, or gets one component's full detail — inputs, outputs, and parameters. **Method:** `list` · `get` | Parameter | Type | Required | Description | | ------------ | ------ | --------- | ----------------------------------------------- | | `connection` | string | Yes | The connection whose component catalog to read. | | `search` | string | No | Free-text filter (for `list`). | | `names` | string | For `get` | Component name(s), comma-separated. | *Read-only.* *** ## Your published workflows Any Workflow your organization publishes as an MCP tool registers alongside the built-in tools, exposing organization-specific logic (site selection, trade-area analysis, demand modeling) in a form the agent can call directly. Published tools run in two modes: * **Sync.** The tool returns results immediately. Best for lightweight, fast queries. * **Async.** The tool launches a job and returns a `jobId`. The agent then polls the [async job tools](#async-job-tools) below and retrieves the output when the job completes. Best for long-running pipelines. Workflows on Redshift and Oracle connections always publish as Async tools, because stored procedures in these data warehouses can't return rows directly. For step-by-step guidance on publishing, see [Workflows as MCP Tools](/carto-user-manual/workflows/workflows-as-mcp-tools). ### How published tools are governed Publishing a Workflow as an MCP tool is a deliberate act by a workflow editor, and it comes with a few properties worth knowing if you are responsible for what agents can run: * **Pinned to a version.** Publishing captures the Workflow as it is at that moment. Editing the Workflow afterwards does not change what the agent runs until someone republishes it (see [Propagating changes](/carto-user-manual/workflows/workflows-as-mcp-tools#propagating-changes)). * **Inputs are defined by the editor.** The editor names and describes every parameter the agent may pass. Nothing else reaches the Workflow. * **Enabling and disabling are recorded.** Both appear in your [Activity Data](/carto-user-manual/settings/activity-data/activity-data-reference) as their own events. * **Runs under the Workflow's connection.** Publishing deploys a stored procedure in your warehouse under that Workflow's connection. The tool's description is free text the model reads to decide when to call it, so editor rights in your organization are the control over what agents are told. See [Which tools an agent can use](/carto-for-agents/mcp-server/tools-reference#which-tools-an-agent-can-use). ### Best practices * **Keep tool descriptions clear and specific**, so the agent chooses the right tool. * **Define inputs precisely** — descriptive names and types for every parameter. * **Test the way an agent will call it.** Use **Run MCP Tool test** in the workflow editor to preview the exact response, including sync/async timing. See [Test your MCP Tool](/carto-user-manual/workflows/workflows-as-mcp-tools#test-your-mcp-tool). * **Choose the right output mode** — Sync for fast queries, Async for long-running processes. * **Version and update carefully.** Sync updates promptly and communicate changes to users. {% hint style="info" %} In **Async** mode, the agent must poll for status and make an extra call to retrieve results. Web-based hosts enforce short request timeouts (around 10 seconds), so use Async for anything that can't finish inside that window. {% endhint %} *** ## Async job tools When you run a workflow with the built-in [`run_workflow`](#run_workflow) tool, its own `status` and `results` methods handle polling — you don't need anything else. The two tools below are for **published workflow tools** running in async mode: they register automatically alongside your published workflows (only when your account has them), so the agent can poll a published async job. You don't configure them. ### `async_workflow_job_get_status_v1_0_0` Gets the status of an async workflow job. The agent calls this after an async workflow tool returns a job ID, and polls until the status is `success` or `failure`. | Parameter | Type | Required | Description | | ---------------- | ------ | -------- | ---------------------------------------------------------------- | | `jobId` | string | Yes | The async workflow job ID returned by the tool that launched it. | | `connectionName` | string | Yes | The connection used by the workflow. | Possible `status` values: `pending`, `running`, `success`, `failure`, `cancelled`. ### `async_workflow_job_get_results_v1_0_0` Retrieves the results of an async workflow job after it completes with `success` status. The agent calls this only after the status tool confirms the job is done. | Parameter | Type | Required | Description | | ------------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- | | `jobId` | string | Yes | The async workflow job ID. | | `providerId` | string | Yes | The data warehouse provider: `bigquery`, `snowflake`, `databricks`, `postgres`, `redshift`, or `oracle`. | | `connectionName` | string | Yes | The connection used by the workflow. | | `workflowOutputTableName` | string | Yes | The fully-qualified name of the workflow output table. | The result is a JSON object with a `rows` array of the output data and a `schema` describing the column types. # Data tools Data tools cover everything between your agent and the data: exploring connections and tables, running SQL, geocoding and routing, importing and exporting, moving data between warehouses, working with named sources, and enriching from the Data Observatory. ## Explore and query ### `explore_data` **Title:** Explore Data **Explores connections and their data, read-only.** Lists connections, inspects one, browses databases/schemas/tables, searches tables by name, and describes a table's or query's columns with per-column statistics. **Method:** `list_connections` · `get_connection` · `list_resources` · `search` · `describe` {% hint style="info" %} On a [token session](/carto-for-agents/mcp-server/connecting-with-api-tokens#what-a-token-unlocks), `list_connections`, `list_resources`, and `search` work with just the **MCP Server** scope; `describe` additionally needs the **Maps** API, and `get_connection` isn't offered — use OAuth for the full method set. {% endhint %} | Parameter | Type | Required | Description | | ----------------- | ------ | ------------------------------------------ | --------------------------------------------------------------- | | `connection_name` | string | For `list_resources`, `search`, `describe` | The connection to work in. | | `fqn` | string | No | A fully-qualified name to browse (for `list_resources`). | | `query` | string | For `search`; optional for `describe` | The search string, or the SQL query to describe. | | `table_fqn` | string | For `describe` | The table to describe (alternative to `query`). | | `column` | string | No | Return per-column stats instead of the schema (for `describe`). | *Read-only.* ### `execute_query` **Title:** Execute SQL Query **Runs a SQL query synchronously and returns rows.** Best for quick `SELECT`s (about a one-minute timeout). For longer queries or `DDL`/`DML`, the agent uses [`execute_async_query`](#execute_async_query). | Parameter | Type | Required | Description | | ----------------- | ------ | -------- | ------------------------------------- | | `connection_name` | string | Yes | The connection to run against. | | `sql` | string | Yes | The SQL to execute. | | `queryParameters` | any | No | Named or positional query parameters. | *Can modify data: runs arbitrary SQL.* ### `execute_async_query` **Title:** Execute Async SQL Query **Runs SQL too slow or large for `execute_query`, or that changes data.** Submits a job, reports status, and cancels. **Method:** `submit` · `status` · `cancel` | Parameter | Type | Required | Description | | ------------ | ------ | ---------------------- | ------------------------------ | | `connection` | string | Yes | The connection to run against. | | `body` | object | For `submit` | The query and any parameters. | | `jobId` | string | For `status`, `cancel` | The job to check or cancel. | *Can modify data.* ## Move data Each of these submits a job and tracks it to completion via a `submit` / `status` method. ### `import_data` **Title:** Import Data **Loads a file into the warehouse from a URL**, then tracks the job. `body` carries the connection, source URL, destination, and options. For the supported formats and the size limit, see: CARTO supports importing **CSV**, **GeoJSON**, **GeoPackage**, **KML**, **KMZ**, **TAB**, **Shapefiles** (in a `.zip` package), and [**GeoParquet**](https://geoparquet.org/) files. These formats can be imported into any connected data warehouse. **GeoTIFF** raster files are also supported when importing into **BigQuery**, **Snowflake**, and **Databricks** connections. The resulting table follows the [**Raquet**](https://github.com/CartoDB/raquet) specification. The size limit for file imports is **5 GB** for all formats. ### `export_data` **Title:** Export Data **Exports a table or query result to a downloadable file** (GeoParquet, GeoJSON, Shapefile, GeoPackage, CSV, and more). `body` carries the connection, source (table or SQL), and format. ### `transfer_data` **Title:** Transfer Data **Copies a table from one connection to another**, with optional reprojection. `body` carries the source and destination connections and tables. *All three can modify data: they write to the warehouse or produce exports.* ## Location Data Services These call CARTO's Location Data Services, and are read-only. Each takes an `operation` that includes a `capabilities` value to discover provider support. ### `geocode` **Title:** Geocode **Geocodes addresses to coordinates, or reverse-geocodes coordinates to addresses.** `operation`: `geocode` · `reverse` · `capabilities`. Geocoding takes an `addresses` array (batched in one call); reverse takes `lat`/`lon`. ### `route` **Title:** Compute Route **Computes a route** between an origin and destination with optional waypoints, returning geometry plus time and distance. `operation`: `route` · `capabilities`. Takes `origin`, `destination`, and travel `mode`. ### `calculate_isolines` **Title:** Calculate Isolines **Computes an isoline** (catchment area) around an origin. `operation`: `isolines` · `capabilities`. Takes `origin`, `mode`, `range`, and `range_type` (`time` or `distance`). ### `calculate_od_matrix` **Title:** Calculate OD Matrix **Computes an origin-destination time/distance matrix.** `operation`: `od_matrix` · `capabilities`. Takes `origins` and `destinations` arrays of `[lon, lat]` points. *All four are read-only.* ## Named sources and Data Observatory ### `manage_named_sources` **Title:** Manage Named Sources **Lists, inspects, creates, and updates named sources** — reusable SQL or table references under a stable name. To remove one, the agent uses [`delete`](/carto-for-agents/mcp-server/tools-reference/workspace-tools#delete). **Method:** `list` · `get` · `create` · `update` | Parameter | Type | Required | Description | | --------- | ------ | ----------------------------- | ------------------------------------------------- | | `name` | string | For `get`, `create`, `update` | The named source's name. | | `source` | string | For `create`, `update` | A SQL query or a fully-qualified table reference. | *Can modify data.* ### `search_data_observatory` **Title:** Search Data Observatory **Searches and browses the CARTO Data Observatory catalog** of public and premium datasets. **Method:** `list_datasets` · `list_filters` · `search_variables` · `get_dataset` · `sample` | Parameter | Type | Required | Description | | ------------ | ------ | --------------------------- | ----------------------------------------------- | | `searchText` | string | No | Free-text catalog search (for `list_datasets`). | | `id` | string | For `get_dataset`, `sample` | The dataset to inspect or sample. | *Read-only.* ### `manage_data_observatory_subscriptions` **Title:** Manage Data Observatory Subscriptions **Lists your Data Observatory subscriptions, subscribes to a dataset, or unsubscribes.** **Method:** `list` · `subscribe` · `unsubscribe` *Can modify data: subscribe and unsubscribe change your subscriptions.* *** ## Connections ### `manage_connections` **Title:** Manage Connections **Creates or updates a data warehouse connection** (BigQuery, Snowflake, Databricks, Postgres, Redshift, Oracle). To list or inspect connections, the agent uses [`explore_data`](#explore_data); to remove one, [`delete`](/carto-for-agents/mcp-server/tools-reference/workspace-tools#delete). **Method:** `create` · `update` | Parameter | Type | Required | Description | | --------- | ------ | ------------ | ----------------------------------------------------------------- | | `body` | object | Yes | The connection payload — full for `create`, partial for `update`. | | `id` | string | For `update` | The connection to update (id or name). | *Can modify data.* # Workspace tools Workspace tools let your agent manage the things around your data: credentials, projects and folders, and — for admins — users, org settings, customizations, and activity exports. There's also a single `delete` tool for removing assets. These are available when you connect over [OAuth](/carto-for-agents/mcp-server/connecting-with-oauth). Some are open to any member; others (managing users, org settings, superadmin operations) require the matching permission on your CARTO account. ## Users ### `manage_users` **Title:** Manage Users **Manages organization members** — list, invite, remove, and handle invitations. **Method:** `list` · `invite` · `delete` · `list_invitations` · `resend_invitation` · `cancel_invitation` | Parameter | Type | Required | Description | | ------------------------------------ | -------------------------------- | ------------ | ------------------------------------------------------- | | `search` / `role_filter` | string | No | Filter the member list. | | `emails` | array | For `invite` | Members to invite. | | `role` | `Builder` \| `Viewer` \| `Guest` | For `invite` | The role granted on acceptance. | | `userId` / `resourcesReceiverUserId` | string | For `delete` | The member to remove, and who inherits their resources. | *Can modify data.* ## Credentials ### `manage_api_access_tokens` **Title:** Manage API Access Tokens **Lists, inspects, creates, and updates API Access Tokens** — the credentials for spatial apps and token-based MCP connections. To remove one, the agent uses [`delete`](#delete). **Method:** `list` · `get` · `create` · `update` | Parameter | Type | Required | Description | | --------- | ------ | ---------------------- | ---------------------------------------------------------------------------------------- | | `id` | string | For `get`, `update` | The token. | | `body` | object | For `create`, `update` | Grants (connection + source), allowed APIs, and optional referers, name, and expiration. | *Can modify data.* ### `manage_oauth_clients` **Title:** Manage OAuth Clients **Lists, inspects, creates, and updates OAuth clients** — the SPA and M2M clients used to sign spatial apps and MCP hosts in. To remove one, the agent uses [`delete`](#delete). **Method:** `list` · `get` · `create` · `update` | Parameter | Type | Required | Description | | --------- | -------------- | ---------------------- | -------------------------------------------------------------------- | | `type` | `spa` \| `m2m` | For `list` | Which clients to list. | | `id` | string | For `get`, `update` | The client. | | `body` | object | For `create`, `update` | The client definition. Note that `update` replaces the whole client. | *Can modify data.* ## Projects ### `organize_projects` **Title:** Organize Projects **Organizes maps and Workflows into projects and folders** — list, get, create, update, and move items. **Method:** `list` · `get` · `create` · `update` · `add_item` · `move_item` · `rename_folder` | Parameter | Type | Required | Description | | --------- | ---------------------- | ---------------------------------- | ----------------------------------------------------------- | | `id` | string | For most methods | The folder or item to act on. | | `body` | object | For `create`, `update`, `add_item` | The folder or item payload. | | `kind` | `folder` \| `shortcut` | For `add_item`, `move_item` | Whether the item is a subfolder or a map/Workflow shortcut. | *Can modify data.* ## Org settings and activity ### `admin_carto` **Title:** Organization Administration **Reads and applies org admin configuration and usage.** Gets settings, applies or diffs a settings bundle, and reads agent status, available models, and org stats. **Method:** `get_settings` · `apply_settings` · `diff_settings` · `agents_status` · `list_agent_models` · `org_stats` | Parameter | Type | Required | Description | | ---------- | ------ | ------------------------------------- | ------------------------------------------------------------------------------------- | | `sections` | array | No | Which settings sections to read (for `get_settings`). | | `bundle` | object | For `apply_settings`, `diff_settings` | Settings keyed by section (basemaps, palettes, maps, connections, workflows, and AI). | *Can modify data: `apply_settings` changes org configuration.* ### `admin_carto_customizations` **Title:** Manage Custom Basemaps **Manages the org's custom basemaps** — list, get, create, and delete. **Method:** `list` · `get` · `create` · `delete` *Can modify data.* ### `export_activity_data` **Title:** Export Activity Data **Exports the organization's activity data for auditing**, then tracks the job. `body` selects the categories (activity, API usage, user list, group list), the format (CSV or Parquet), and the time range. **Method:** `submit` · `status` *Exports org data.* ### `superadmin_carto_resources` **Title:** Organization Resources (Superadmin) **Lists, transfers, or batch-deletes resources belonging to any user in the org.** Requires the elevated superadmin role. **Method:** `list` · `transfer` · `batch_delete` *Can modify data: transfer and batch-delete change ownership or remove resources.* *** ## Deleting assets ### `delete` **Title:** Delete Asset **Permanently deletes one CARTO asset.** A single tool covers every deletable asset type, selected by `kind`. **Kind:** `map` · `workflow` · `connection` · `named_source` · `oauth_client` · `token` · `project_item` | Parameter | Type | Required | Description | | ----------- | ---------------------- | ------------------ | --------------------------------------------------------- | | `id` | string | Yes | The asset to delete (a connection also accepts its name). | | `item_kind` | `folder` \| `shortcut` | For `project_item` | Whether the project item is a folder or a shortcut. | *Can delete data. To remove a user, the agent uses* [*`manage_users`*](#manage_users) *instead, so resources can be reassigned.* {% hint style="warning" %} `delete` is permanent. On hosts that ask for confirmation before destructive actions, the agent surfaces the request; CARTO annotates this tool as destructive so hosts can prompt. {% endhint %} # CARTO Agent Skills **CARTO Agent Skills** is a public catalog of short, on-demand playbooks that teach AI coding agents how to drive the CARTO platform fluently. The repository is at [`CartoDB/agent-skills`](https://github.com/CartoDB/agent-skills) on GitHub. ## Why agent skills? Generic LLMs know *about* CARTO but make small mistakes when actually driving it: the wrong tool for the job, an outdated SQL dialect, a missing async-job handshake, the wrong import shape for a tileset. Each skill is a focused playbook the agent loads on demand when a request matches its domain, so the agent ships idiomatic, working CARTO output the first time. The skills route the agent to the **right access path** for each task. For most work — exploring data, creating and editing maps, building and running Workflows — that path is the [CARTO MCP Server](/carto-for-agents/mcp-server), which the agent calls inline. The skills reach for the [CARTO CLI](/carto-for-agents/cli) when a task calls for scripting, CI/CD, headless runs, bulk and cross-organization operations, or deeper administration and auditing (such as querying usage logs). You don't choose; the skill picks based on what you're asking for and what's available. ## Three tiers The catalog is organized in three layered tiers. An agent routes to the right skill automatically based on user intent. * **Utility**. Foundational CARTO primitives (setup, connect, query, explore). Loaded by other skills as a shared base. * **Platform**. CARTO product surfaces (workflows, Builder maps, imports, Data Observatory, org admin). Build on the utility tier. * **Use-case patterns**. Recipe skills that compose platform skills into end-to-end spatial analyses (hotspot analysis, site selection, trade areas, GWR). Each carries trigger keywords so the agent routes on user intent. For the full catalog with descriptions and trigger keywords, see [Skills catalog](/carto-for-agents/agent-skills/skills-catalog). For the layering rationale, see [`ARCHITECTURE.md`](https://github.com/CartoDB/agent-skills/blob/master/ARCHITECTURE.md) in the repo. ## Installing the skills The catalog ships ready-made install manifests for **Claude Code, Claude.ai, Claude Desktop, Codex, Gemini CLI, and the Skills CLI** today, all from the same upstream source. For hosts that take skills through an upload form, such as **Gemini Enterprise**, each skill is also published as a ready-made ZIP. Any other coding agent that supports a compatible plugin or rules mechanism can consume the same catalog. See [Installation](/carto-for-agents/agent-skills/installation) for the per-agent commands, and [Connect your platform](/carto-for-agents/connect-your-platform) to set up CARTO end to end in your agent. ## How it composes with the rest of CARTO for Agents * The skills route to the [**CARTO MCP Server**](/carto-for-agents/mcp-server) for inline, in-conversation work — exploring connections, creating and editing maps, building and running Workflows, and running SQL. Connect the MCP Server so these tools are available in your agent. * They reach for the [**CARTO CLI**](/carto-for-agents/cli) when a task calls for scripting, CI/CD, headless runs, bulk or cross-organization operations, deeper administration and auditing (like SQL over usage logs), or the fullest command surface. Skills that need the CLI say so and walk first-time users through install and login (`carto-basics`). * As you publish Workflows as MCP tools, the same Workflows become callable through the MCP Server, and the skills know to use them. ## Source of truth This documentation summarizes the catalog as it ships today. The canonical, always-up-to-date source is the public repo at [`CartoDB/agent-skills`](https://github.com/CartoDB/agent-skills), specifically `skills/catalog.json`, which lists every shipped skill, its tier, its dependencies, and its description. # Installation CARTO Agent Skills are distributed from the public repo at [`CartoDB/agent-skills`](https://github.com/CartoDB/agent-skills). There are two ways to add them, depending on your agent. * **Install from the repository.** Claude Code, Claude.ai, Claude Desktop, Codex, Gemini CLI and the Skills CLI install the whole catalog from the repo and keep it up to date. * **Upload skill ZIPs.** Gemini Enterprise and Microsoft Copilot Studio take skills through an upload form, one skill at a time. Snowflake and Databricks load skills their own way. See [Snowflake CoWork](/carto-for-agents/connect-your-platform/snowflake-cowork), [Snowflake CoCo](/carto-for-agents/connect-your-platform/snowflake-coco) and [Databricks](/carto-for-agents/connect-your-platform/databricks). ## Prerequisites Before installing the skills, you need: * A [**CARTO account**](https://carto.com/signup) with workspace access. * An AI agent that can load skills. See the instructions for each agent below. Many skills route through the [CARTO MCP Server](/carto-for-agents/mcp-server), which needs no local install. [Connect it](/carto-for-agents/connect-your-platform) so its tools are available to your agent, including creating and editing maps and Workflows. Skills that script, run headless, do bulk and cross-organization work, or handle deeper administration and auditing (such as querying usage logs) use the [**CARTO CLI**](/carto-for-agents/cli). Install and authenticate it when you need those. ```bash npm install -g @carto/carto-cli carto auth login carto auth status # confirm: ✓ Authenticated ``` The `carto-basics` skill walks first-time users through CLI install, login, and profile setup. ## Install from the repository ### Claude Code Install via the Claude Code plugin marketplace: ``` /plugin marketplace add CartoDB/agent-skills /plugin install carto-skills@carto-agent-skills ``` All skills ship together as a single bundle (`carto-skills`). Once installed, Claude Code routes to individual skills automatically based on the user's request, so there's nothing else to invoke. ### Claude.ai and Claude Desktop Claude.ai and Claude Desktop install the same plugin as Claude Code. Open **Customize > Plugins**, click **+** in **Personal plugins**, select **Add marketplace > Add from a repository**, and enter `CartoDB/agent-skills`. Then install **carto-skills**. See [Claude](/carto-for-agents/connect-your-platform/claude#add-the-carto-agent-skills) for the full steps, including how organization admins share it. If you can't use plugins, [upload the skill ZIPs](#upload-skill-zips) instead. ### Codex The Codex plugin manifest is at [`.codex-plugin/plugin.json`](https://github.com/CartoDB/agent-skills/blob/master/.codex-plugin/plugin.json) in the repo. Install it with your Codex client's extension command. See [Codex](/carto-for-agents/connect-your-platform/codex) for the full setup. ### Gemini CLI The Gemini extension manifest is at [`gemini-extension.json`](https://github.com/CartoDB/agent-skills/blob/master/gemini-extension.json), with one command per skill under [`commands/carto/`](https://github.com/CartoDB/agent-skills/tree/master/commands/carto). After install, invoke a skill with `/carto:`, for example `/carto:carto-basics`. ### Skills CLI ```bash npx skills add CartoDB/agent-skills ``` The Skills CLI reads `skills/catalog.json` from the repo and registers each skill independently. Use it when you want to install a subset. ### Other agents Any agent that can load a skill, plugin, or rules file from a repo can use the same skills. Point it at [`CartoDB/agent-skills`](https://github.com/CartoDB/agent-skills) and its `skills/catalog.json`. ## Upload skill ZIPs Some agents take skills through an upload form, one skill at a time, as a **ZIP file with `SKILL.md` at the archive root**. You don't need to clone or zip anything, since every skill is published as a ready-made ZIP that always reflects the current version. ``` https://github.com/CartoDB/agent-skills/releases/latest/download/.zip ``` The **Download** column of the [Skills catalog](/carto-for-agents/agent-skills/skills-catalog) has the link for each skill. ### Gemini Enterprise Open **Skills**, click **Upload skill**, and drop the ZIP. Gemini reads the skill name and description from `SKILL.md` and turns the skill on. See [Google Gemini Enterprise](/carto-for-agents/connect-your-platform/google-gemini-enterprise#add-the-carto-agent-skills) for how an administrator enables skills first. ### Microsoft Copilot Studio Open your agent on the **Build** tab, click **+** next to **Skills**, choose **Upload a skill**, and drop the ZIP. See [Microsoft Copilot Studio](/carto-for-agents/connect-your-platform/microsoft-copilot-studio#add-the-carto-agent-skills). ### Claude without plugins Go to **Settings > Capabilities > Skills**, click **Upload skill**, and choose the ZIP. {% hint style="info" %} Skills are layered. A use-case skill relies on `carto-create-workflow`, which relies on the utility skills. Upload forms don't follow those references, so upload the dependencies too, starting with the four utility skills. See [Dependencies and routing](/carto-for-agents/agent-skills/skills-catalog#dependencies-and-routing). {% endhint %} ## Upgrading Skills ship continuously from upstream `master`. The catalog version is tracked in [`skills/catalog.json`](https://github.com/CartoDB/agent-skills/blob/master/skills/catalog.json) at the repo root. * **Installed from the repository.** Refresh or reinstall through your agent to pull the latest catalog. * **Uploaded as ZIPs.** Uploaded skills don't update themselves. Download the ZIP again from the [Skills catalog](/carto-for-agents/agent-skills/skills-catalog) and upload it. The agent asks whether to replace the existing skill of the same name. ## Verify the install Once installed, ask your agent something CARTO-specific that maps to a skill, for example: > "List my CARTO maps." > > "Connect to my BigQuery warehouse called `analytics` and show me the available tables." > > "Run a hotspot analysis on the `crashes_2024` table." If the skills are installed correctly, the agent will route to the appropriate skill (`carto-basics`, `carto-explore-datawarehouse`, `carto-hotspot-analysis`, …), follow the skill's playbook, and drive CARTO on your behalf through the MCP Server or the CLI, whichever fits the request. # Skills catalog The CARTO Agent Skills catalog ships **23 skills** organized in three tiers. The list below is a snapshot; the canonical, always-up-to-date catalog is [`skills/catalog.json`](https://github.com/CartoDB/agent-skills/blob/master/skills/catalog.json) in the public repo. The **Download** column gives the ZIP for agents that take skills through an upload form, such as Gemini Enterprise and Microsoft Copilot Studio. See [Installation](/carto-for-agents/agent-skills/installation#upload-skill-zips). ## Utility tier Foundational CARTO primitives. No dependencies; loaded by other skills as a shared base. | Skill | Description | Download | | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | [`carto-basics`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-basics) | Start here for first-time CARTO use. Orients on the two access paths — the MCP Server (the primary path for inline, in-conversation work) and the CLI (for scripting, CI/CD, headless and bulk/cross-org work, and deeper administration) — and covers CLI install, authentication, profiles, JSON output, and async job patterns. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-basics.zip) | | [`carto-connect-datawarehouse`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-connect-datawarehouse) | Choose and configure the data warehouse engine connection for CARTO (BigQuery, Snowflake, Redshift, Postgres, Databricks, Oracle). | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-connect-datawarehouse.zip) | | [`carto-query-datawarehouse`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-query-datawarehouse) | Write spatial SQL against the connected warehouse — dialect-specific guidance, performance defaults, and CARTO's query/job execution model. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-query-datawarehouse.zip) | | [`carto-explore-datawarehouse`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-explore-datawarehouse) | Discover what's in the connected warehouse — schemas, tables, columns, and CARTO named sources. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-explore-datawarehouse.zip) | ## Platform tier CARTO product surfaces. Depend only on utility skills. | Skill | Description | Download | | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | [`carto-import-export-data`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-import-export-data) | Import geospatial files into the data warehouse via CARTO, export results back out, and prepare tilesets for fast map rendering. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-import-export-data.zip) | | [`carto-create-workflow`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-workflow) | Build, schedule, and operate analytics DAGs in CARTO Workflows — the no-code/low-code orchestration layer over the data warehouse. Triggers when the user wants to author a workflow, run/edit one, schedule a DAG, or copy a workflow across profiles or orgs. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-create-workflow.zip) | | [`carto-find-spatial-data`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-find-spatial-data) | Discover and subscribe to external spatial datasets via CARTO Data Observatory and partner catalogs. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-find-spatial-data.zip) | | [`carto-manage-platform`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-manage-platform) | Administer the CARTO org — users, roles, quotas, activity audit, and bulk resource operations. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-manage-platform.zip) | | [`carto-create-builder-maps`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-builder-maps) | Author, edit, publish, and validate CARTO Builder maps. Routes to the MCP Server's map tools (`create_map`, `update_map`, `validate_map`, `read_maps`, `view_map`) when attached, and to the `carto maps` CLI for scripted/bulk authoring, cross-org copy, screenshots, or when the server isn't attached. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-create-builder-maps.zip) | | [`carto-render-inline-map`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-render-inline-map) | Render an ad-hoc interactive map inline in the chat from a deck.gl declarative spec via the CARTO MCP Server's `view_map` tool. For exploratory / throwaway visualizations; triggers on "show me X on a map", "visualize Y", "make a heatmap of Z". | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-render-inline-map.zip) | | [`carto-preview-builder-map`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-preview-builder-map) | Preview an existing saved CARTO Builder map inline in the chat via the CARTO MCP Server — resolve the map with `read_maps` (by name or search), then render it with `view_map` by map ID. Renders a lightweight read-only preview. Triggers on "show me the X map", "open the Y map", and inline previews of a freshly-created map. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-preview-builder-map.zip) | | [`carto-develop-app`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-develop-app) | Generate a working geospatial application powered by CARTO and deck.gl: basemap, layers (vector / H3 / quadbin / raster), widgets, filters, legend, inputs, optional chat-with-map agent, and the right auth strategy (public token, OAuth, SSO, or M2M). | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-develop-app.zip) | ## Use-case tier Recipe skills that compose platform skills into end-to-end spatial analyses. Each carries trigger keywords so the agent routes on user intent. | Skill | Description & triggers | Download | | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | [`carto-hotspot-analysis`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-hotspot-analysis) | Builds Getis-Ord Gi\* hotspot analysis workflows. Triggers on: hotspots, coldspots, spatial clusters, Getis-Ord, Gi\*, cluster detection, concentration areas, spacetime hotspot, temporal clusters, time-varying patterns, hotspot trends, emerging hotspots, Mann-Kendall. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-hotspot-analysis.zip) | | [`carto-spatial-autocorrelation`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-spatial-autocorrelation) | Builds Moran's I spatial autocorrelation workflows. Triggers on: spatial autocorrelation, Moran's I, spatial dependency, HH/HL/LH/LL quadrants, LISA, spatial weight matrix, classifying locations into cluster types. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-spatial-autocorrelation.zip) | | [`carto-gwr`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-gwr) | Builds Geographically Weighted Regression (GWR) workflows. Triggers on: GWR, geographically weighted regression, spatially varying relationships, local regression, local coefficients, spatial non-stationarity. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-gwr.zip) | | [`carto-spatial-enrichment`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-spatial-enrichment) | Spatial enrichment workflows. Triggers on: enrich, add demographics, estimate population around locations, compute spatial features, sociodemographic analysis, trade-area enrichment. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-spatial-enrichment.zip) | | [`carto-trade-area-analysis`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-trade-area-analysis) | Trade area and catchment analysis. Triggers on: trade area, catchment area, isochrone, drive time, walk time, billboard placement, OOH audience targeting, scoring candidate locations. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-trade-area-analysis.zip) | | [`carto-site-selection`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-site-selection) | Site selection and cannibalization analysis. Triggers on: site selection, cannibalization, new store location, optimal location, twin areas, look-alike areas. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-site-selection.zip) | | [`carto-territory-planning`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-territory-planning) | Territory planning combining territory balancing and location allocation. Triggers on: sales territories, service zones, balanced territories, location allocation, depot/hub placement, response-time optimization, demand coverage. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-territory-planning.zip) | | [`carto-routing-od-analysis`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-routing-od-analysis) | Routing and origin-destination analysis. Triggers on: routing, travel time, OD matrix, isoline, isochrone, catchment area, drive-time polygon, accessibility analysis, commute patterns, OD flow, shortest-path computation. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-routing-od-analysis.zip) | | [`carto-geocoding`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-geocoding) | Geocoding workflows that convert addresses or place names into coordinates. Triggers when the user has tabular data with addresses but no geometry column. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-geocoding.zip) | | [`carto-composite-scoring`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-composite-scoring) | Composite-score workflows. Triggers on: composite scores, indexes, multi-variable rankings, market potential, resilience indexes, risk indexes, weighted scores, PCA, supervised/unsupervised scoring. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-composite-scoring.zip) | | [`carto-arcgis-migration`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-arcgis-migration) | End-to-end ArcGIS Portal / AGOL to CARTO migration. Three phases over a shared `MIGRATION_MANIFEST.md`: discover (enumerate and classify items), migrate-data (Hosted Feature Layers / Tables → CARTO tables), migrate-maps (Web Maps and simple Dashboard / Web Experience / Web Mapping Application entries → CARTO Builder maps). Default mode is batch; migrated maps are tagged `From ArcGIS` and created as private. Triggers when the user wants to migrate ArcGIS content to CARTO, asks "what's in my Portal", or names a Portal/AGOL URL. | [ZIP](https://github.com/CartoDB/agent-skills/releases/latest/download/carto-arcgis-migration.zip) | ## Dependencies and routing Use-case skills depend on `carto-create-workflow`. Platform skills depend on the relevant utility skills (e.g. `carto-create-workflow` depends on `carto-basics`, `carto-connect-datawarehouse`, and `carto-query-datawarehouse`; `carto-render-inline-map` and `carto-preview-builder-map` depend only on `carto-basics`). When a use-case skill is triggered, the agent loads it along with its dependency chain. If you upload skills manually (Claude.ai, Gemini Enterprise), upload the dependency chain as well, since upload forms don't resolve it. Routing happens via skill descriptions and trigger keywords (the catalog descriptions above). Phrasing your request with one of the trigger keywords is the most reliable way to route into a specific skill. # CARTO CLI The **CARTO CLI** (`@carto/carto-cli`) is the official command-line interface for CARTO. It exposes nearly every platform operation as a scriptable command. Find and manage maps, workflows, connections and credentials, import and export geospatial data, run SQL on connected warehouses, manage users, audit activity, transfer assets between organizations, and chat with the AI agents configured on your maps. The CLI is designed to be driven by: * **Humans** at the terminal, for one-off admin tasks, scripting, and CI/CD. * **AI agents** like Claude Code, Cursor, Codex, or Gemini CLI through tool use. The `--json` global flag gives agents machine-readable output for every command. {% hint style="info" %} **Most users don't need the CLI to start.** For chatting with your data — creating maps, running Workflows, exploring your warehouse — the [CARTO MCP Server](/carto-for-agents/mcp-server) is the shortest path and needs no install. Reach for the CLI when you want scripting, CI/CD, and headless automation; bulk or cross-organization operations; deeper administration and auditing (including SQL over your usage logs); or the most complete command surface. {% endhint %}

## Capabilities * **Builder maps**. Create, update, validate, publish, and copy CARTO Builder maps from a round-trippable JSON bundle. Inspect the AI agent surface available on each map. (Map `screenshot` is also available as an experimental command.) * **Workflows**. Create, update, validate, verify, run, schedule, share, and publish CARTO Workflows. Publish a workflow as an MCP tool so any connected agent can call it. Install workflow extensions and browse the component catalog. * **Projects (folders)**. Group maps and workflows into projects, with a local-sync workflow that lets you clone, edit, and push changes back from your machine. * **Credentials**. Create and manage API Access Tokens, SPA OAuth clients, M2M OAuth clients, and Named Sources. * **Connections**. List, create, update, and delete data warehouse connections. Browse the resource tree, search tables, and describe schemas. * **Data Observatory**. Browse, search, and subscribe to spatial datasets from CARTO's public and premium catalog. * **Data movement**. Import geospatial files (CSV, GeoJSON, GeoPackage, GeoParquet, KML, KMZ, TAB, Shapefile) from local files or URLs. Export warehouse tables back out, or transfer data between warehouses. * **SQL**. Run SQL queries and DDL/DML jobs against your data warehouse from the terminal. * **Organization and users**. View quotas, resources, and AI limits. List, invite, and manage users and pending invitations. * **Activity data**. Query and export usage logs via DuckDB SQL (Enterprise Large+). * **Superadmin operations**. Batch operations and cross-org resource transfers. * **Multi-profile support**. Manage multiple CARTO accounts or environments with named profiles. Tokens are stored locally in `~/.carto_credentials.json`. * **Single executable**. Bundled into one file with minimal dependencies. * **JSON output**. Machine-readable output (`--json`) on every command for scripting and agent tool use. ## Get started 1. [Install the CLI](/carto-for-agents/cli/installation). 2. [Authenticate](/carto-for-agents/cli/authentication) to your CARTO organization with `carto auth login`. Configure additional [named profiles](/carto-for-agents/cli/authentication#multiple-profiles) if you work with several organizations. 3. [Browse the command reference](/carto-for-agents/cli/command-reference) to see every available command, flag, and example. 4. Walk through end-to-end [examples](/carto-for-agents/cli/examples): creating Builder maps and workflows from JSON, copying assets between organizations, scheduling workflows, importing data, and querying activity logs. If you're driving the CLI from an AI coding agent, also see [CARTO Agent Skills](/carto-for-agents/agent-skills), the catalog of skills that teach coding agents how to use the CLI idiomatically. # Installation The CARTO CLI is published on npm as [`@carto/carto-cli`](https://www.npmjs.com/package/@carto/carto-cli) and installs as a global `carto` binary. ## Prerequisites * **Node.js 22 or newer.** Check with `node --version`. * A CARTO organization. The CLI works against CARTO Cloud (any region) and CARTO Self-Hosted deployments. {% hint style="warning" %} **CARTO Self-Hosted compatibility** The CARTO CLI evolves with the rest of the CARTO Platform. The latest version of the CARTO CLI will always be compatible with CARTO Cloud. However, newer versions of the CLI might not be compatible with older versions of CARTO Self-Hosted deployments, due to missing API functionalities. For a full compatibility list, check the [CARTO Self-Hosted release notes](/carto-self-hosted/release-notes). {% endhint %} ## Install via npm ```bash npm install -g @carto/carto-cli ``` Verify the install: ```bash carto --version carto --help ``` ## Upgrade ```bash npm install -g @carto/carto-cli@latest ``` ## Next steps * [Authenticate](/carto-for-agents/cli/authentication) to your CARTO organization with `carto auth login`. * If you manage multiple CARTO organizations or environments, set up [named profiles](/carto-for-agents/cli/authentication#multiple-profiles). # Authentication & profiles The CLI authenticates to CARTO with an OAuth 2.0 + PKCE browser flow. The first time you run `carto auth login`, the CLI opens your browser, you complete the standard CARTO login (including SSO if your organization requires it), and the CLI captures the resulting access token and stores it locally. ## Logging in ```bash # Interactive browser-based login (recommended) carto auth login # Login to a named profile carto auth login staging ``` The login flow: 1. Displays an authorization URL. 2. Opens your browser (you may need to copy/paste the URL manually in headless environments). 3. Waits for you to complete the login. 4. Captures the access token and your user/organization info. 5. Stores the credentials in `~/.carto_credentials.json`. 6. Configures the API base URL based on your tenant. ### Logging in to a specific organization (with or without SSO) If your organization uses SSO, or if you have access to multiple organizations, log in with the organization name: ```bash # Standard organization name carto auth login --organization-name production # Organization name with spaces (requires quotes) carto auth login --organization-name "ACME Corporation" # Save to a specific profile carto auth login acme-prod --organization-name "ACME Corporation" ``` How it works: 1. The CLI queries your organization's SSO configuration from the CARTO API. 2. **If SSO is configured:** the browser opens to your organization's SSO login page (SAML/OIDC). 3. **If SSO is not configured:** standard OAuth login proceeds. 4. The organization context is preserved for re-authentication. **Requirements:** * Use the exact organization name (case-sensitive, include spaces in quotes). * For SSO logins, your organization administrator must have configured SSO in CARTO. ### Auth login options | Option | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------------------- | | `--env ` | Auth environment: `production`, `staging`, `local`, `dedicated-NN`. Only set this if instructed by support. | | `--organization-name ` | Organization name for SSO login. Use quotes if the name contains spaces. | | `--organization-id ` | Organization ID for SSO login (future support). | ## Checking status ```bash carto auth status # Status of the current profile carto auth status production # Status of a named profile ``` Example output: ``` $ carto auth status ✓ Authenticated Current profile: my-org/me@example.com (default) Token source: credentials Token: eyJhbGciOiJSUzI1NiIs... Expiration: 23/10/2025, 12:42:45 Time remaining: (in 18 hours) Status: 🟢 Valid Tenant: clausa.app.carto.com (gcp-us-east1) Organization: my-org (ac_abc123) User: me@example.com ``` `carto auth whoami` returns the current user's profile (user ID, name, email, account info, roles). ## Token lifetime and re-authentication Access tokens typically expire after 24 hours. The CLI extracts the expiration from the JWT and surfaces it in `carto auth status`: | Indicator | Meaning | | -------------------- | ---------------------------------------------------------------------- | | 🟢 **Valid** | More than 10% of token lifetime remaining. | | 🟡 **Expiring soon** | Less than 10% of lifetime remaining (\~2.4 hours for a 24-hour token). | | 🔴 **Expired** | Token has expired and must be renewed. | When a token is expiring or expired, the CLI suggests a context-aware re-authentication command that preserves your profile, environment, and (if applicable) organization name — so you don't accidentally create a duplicate profile or end up in the wrong environment. ``` ⚠️ Warning: Token is expiring soon Less than 10% of token lifetime remaining Consider re-authenticating to avoid interruptions: carto auth login my-profile ``` ## Logging out ```bash carto auth logout # Logout from the current profile carto auth logout staging # Logout from a named profile ``` This removes the stored credentials for that profile. ## Multiple profiles Use **named profiles** when you work with more than one CARTO organization (production vs. staging, multiple customer accounts, multiple regions, …). Each profile holds its own credentials and tenant configuration. A profile represents authentication to a specific: * **Tenant** (infrastructure region) — e.g. `gcp-us-east1`, `onp-acme-prod` (self-hosted). * **Organization** (account) — e.g. `team`, `carto-prod`. * **User** (authenticated user) — e.g. `user@company.com`. ```bash # Login to multiple profiles carto auth login # Auto-suggests: tenant_id/org_name/user@email.com carto auth login staging carto auth login production # Switch the current default profile carto auth use production carto auth use staging # Use a specific profile for a single command (overrides default) carto --profile staging maps list carto --profile production workflows list # List all profiles and the current default carto auth status # Logout removes only that profile carto auth logout staging ``` `carto auth status` (with no arguments) shows the full hierarchy: tenant → organization → user, plus all available profiles with the current default marked. **Profile management notes:** * **Auto-generated names** — Login without a name suggests profiles in the format `tenant_id/org_name/user@email.com`. * **Custom names** — Provide a short name during login (e.g., `staging`, `production`). * **Current profile** — The default used when `--profile` is not specified. * **Override per command** — Use `--profile ` on any command, or set `CARTO_PROFILE` in the environment. * **Backwards compatibility** — Old single-profile credentials files are migrated automatically on first use. For a detailed walkthrough of using profiles to copy maps and workflows between organizations, see [Examples → Copying maps and workflows between organizations](/carto-for-agents/cli/examples#copying-maps-and-workflows-between-organizations). ## Credentials storage See [Configuration](/carto-for-agents/cli/configuration) for the credentials file format, environment variables, and authentication priority. # Configuration ## Credentials file The CLI stores authentication credentials in `~/.carto_credentials.json` with support for multiple profiles: ```json { "current_profile": "production", "profiles": { "production": { "token": "your-bearer-token", "tenant_id": "gcp-us-east1", "tenant_domain": "carto.acme.com", "organization_id": "ac_yv1im1y2", "organization_name": "carto-prod", "user_email": "user@acme.com" }, "staging": { "token": "staging-bearer-token", "tenant_id": "gcp-us-east1", "tenant_domain": "carto-dev.acme.com", "organization_id": "ac_7p1sk0gs", "organization_name": "Carto-Dev", "user_email": "dev@acme.com" } } } ``` **Structure:** * `current_profile` — the default profile used when `--profile` is not specified. * `profiles` — every saved profile keyed by name. Each entry holds: * `token` — bearer token (stored without the `Bearer` prefix). * `tenant_id` — infrastructure region (e.g. `gcp-us-east1`, `onp-acme-prod` for a self-hosted tenant). * `tenant_domain` — organization domain (e.g. `carto.acme.com`). * `organization_id` — account ID (e.g. `ac_yv1im1y2`). * `organization_name` — human-readable organization name. * `user_email` — authenticated user email. The API base URL is automatically constructed as `https://{tenant_id}.api.carto.com`. {% hint style="info" %} Old-format credentials files (single profile at the root level) are automatically migrated to this nested structure on first use. {% endhint %} ## Authentication priority The CLI looks for credentials in this order. The first source found wins: 1. The `--token` flag on the command line. 2. The `CARTO_API_TOKEN` environment variable. 3. The credentials file (`~/.carto_credentials.json`). 4. Legacy config file (`~/.carto/config.json`) — for backwards compatibility. ## Environment variables | Variable | Description | | ----------------- | ---------------------------------------------------------------------- | | `CARTO_API_TOKEN` | API token for authentication. Overrides the credentials file. | | `CARTO_PROFILE` | Profile to use. Overrides `current_profile` from the credentials file. | | `CARTO_AUTH_ENV` | Auth environment. Only set if instructed by support. | | `CARTO_AUTH_PORT` | Callback server port for the OAuth login flow. Default: `3003`. | ### Proxies The CLI follows the same proxy variables as curl and git. Set `HTTPS_PROXY` (or `HTTP_PROXY`) to route requests through a corporate proxy, and list in `NO_PROXY` the hosts that must be reached directly, such as a Self-Hosted CARTO instance on an internal-only hostname. | Variable | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `HTTPS_PROXY`, `HTTP_PROXY` | Proxy URL for outgoing requests. `HTTPS_PROXY` is used when both are set, for `http` and `https` targets alike. | | `NO_PROXY` | Comma-separated hosts that bypass the proxy: an exact host (`carto.internal.example.com`), a domain suffix with a leading dot (`.example.com`), `*.example.com`, `host:port`, or `*` for everything. | Lowercase names (`https_proxy`, `no_proxy`) work too. A bare domain such as `example.com` only matches that exact host, not its subdomains; use the leading dot form to cover them. ```bash # Self-Hosted instance on an internal hostname, behind a corporate proxy export HTTPS_PROXY="http://proxy.example.com:8080" export NO_PROXY=".example.com,localhost,127.0.0.1" carto projects list ``` ## Global flags These flags work with every command: | Flag | Description | | ------------------ | --------------------------------------------------------------------- | | `--json` | Output in JSON format. Use for scripting and agent tool use. | | `--debug` | Show request details (method, URL, headers, body). Tokens are masked. | | `--token ` | Override the API token for this command. | | `--base-url ` | Override the base API URL. | | `--profile ` | Use a specific profile (default: the `current_profile` value). | | `--version`, `-v` | Show version. | | `--help`, `-h` | Show help. | ### Debugging requests ```bash # Show full request details for any command carto --debug maps list # Combine with --json for clean output + visible request internals carto --debug --json auth status ``` Debug output includes the HTTP method, full URL, request headers (with the token masked), and the request body for `POST` / `PATCH` requests. ### Using environment variables ```bash # Authenticate via env var (useful in CI/CD) export CARTO_API_TOKEN="eyJhbGc..." carto maps list # Override with CLI flags carto --token "different-token" --base-url "https://eu-west1.api.carto.com" maps list ``` # Command reference Every CARTO CLI command, organized by command group. The CLI uses a hierarchical structure: ``` carto [global-options] [args...] ``` For global options (`--json`, `--debug`, `--profile`, …) and environment variables, see [Configuration](/carto-for-agents/cli/configuration). | Group | Purpose | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | [`auth`](/carto-for-agents/cli/command-reference/auth) | Personal authentication: log in, log out, switch profiles, check status. | | [`credentials`](/carto-for-agents/cli/command-reference/credentials) | Manage application credentials (API tokens, SPA OAuth clients, M2M OAuth clients). | | [`maps`](/carto-for-agents/cli/command-reference/maps) | Manage Builder maps: create, update, validate, publish, schema, agents, copy, screenshot (experimental). | | [`workflows`](/carto-for-agents/cli/command-reference/workflows) | Manage Workflows: create, update, validate, verify, run, share, schedule, mcp publish. | | [`projects`](/carto-for-agents/cli/command-reference/projects) | Manage projects (folders) that group maps and workflows, with local-sync workflow. | | [`connections`](/carto-for-agents/cli/command-reference/connections) | Manage data warehouse connections. | | [`named-sources`](/carto-for-agents/cli/command-reference/named-sources) | Manage Named Sources — server-side aliases for SQL queries. | | [`do`](/carto-for-agents/cli/command-reference/do) | Data Observatory: browse, search, sample, subscribe to spatial datasets. | | [`imports`](/carto-for-agents/cli/command-reference/imports) | Import geospatial files (CSV, GeoJSON, GeoPackage, Shapefile, …) from local files or URLs. | | [`export`](/carto-for-agents/cli/command-reference/export) | Export warehouse tables to file (GeoParquet, GeoJSON, Shapefile, CSV, …) or cloud storage. | | [`transfer`](/carto-for-agents/cli/command-reference/transfer) | Transfer data between warehouses. | | [`sql`](/carto-for-agents/cli/command-reference/sql) | Run SQL queries (returns results) and SQL jobs (DDL/DML) on your data warehouse. | | [`lds`](/carto-for-agents/cli/command-reference/lds) | Location Data Services: geocoding, reverse geocoding, isolines, routing, OD matrices. | | [`org`](/carto-for-agents/cli/command-reference/org) | View organization statistics, resources, and quotas. | | [`users`](/carto-for-agents/cli/command-reference/users) | Manage organization users and pending invitations. | | [`activity`](/carto-for-agents/cli/command-reference/activity) | Query and export activity logs and usage data (Enterprise Large+). | | [`admin`](/carto-for-agents/cli/command-reference/admin) | Superadmin operations: list-all, batch-delete, transfer. | | [`ai`](/carto-for-agents/cli/command-reference/ai) | Chat with map AI agents (`aifeature`) and access CARTO's LLM proxy (`aiproxy`). | | [`app`](/carto-for-agents/cli/command-reference/app) | Hosted apps: deploy a frontend bundle behind your organization login, or package a public build you host yourself. | # auth Personal authentication to CARTO. Manage login sessions, named profiles, and view current user information. For an overview of the OAuth flow, profiles, and re-authentication behavior, see [Authentication & profiles](/carto-for-agents/cli/authentication). ## `carto auth login [profile]` Open a browser-based OAuth 2.0 + PKCE login flow and store the resulting credentials. ```bash carto auth login # Login to default profile carto auth login staging # Login to a named profile carto auth login --organization-name "ACME" # Organization-specific login (SSO or standard) carto auth login acme-prod --organization-name "ACME Corporation" ``` **Arguments:** * `[profile]` — Optional profile name. If omitted, an auto-generated name `tenant_id/org_name/user@email.com` is used. **Options:** | Option | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------ | | `--env ` | Auth environment: `production`, `staging`, `local`, `dedicated-NN`. Only set if instructed by support. | | `--organization-name ` | Organization name for SSO login. Use quotes if it contains spaces. | | `--organization-id ` | Organization ID for SSO login (future support). | ## `carto auth logout [profile]` Remove stored credentials. ```bash carto auth logout # Logout from default profile carto auth logout staging # Logout from named profile ``` ## `carto auth status [profile]` Show authentication status, token expiration, and the full tenant → organization → user hierarchy. With no arguments, also lists every available profile and marks the current default. ```bash carto auth status carto auth status production ``` ## `carto auth use ` Set the given profile as the current default. Subsequent commands will use it unless overridden by `--profile` or `CARTO_PROFILE`. ```bash carto auth use production ``` ## `carto auth whoami` Show the authenticated user's profile (user ID, name, email, account info, roles). ```bash carto auth whoami ``` On an M2M profile there is no user profile to show, so `whoami` reports the service identity instead: client id, account id, the user the client acts on behalf of, API base URL and token expiry. API access tokens created from an M2M session are attributed to that acting user. # credentials Manage application credentials — API tokens, SPA OAuth clients, and M2M OAuth clients. These credentials are separate from your personal authentication (`carto auth login`) and are used by applications and backend services to call CARTO APIs. **Credential types:** * **API Access Tokens** — server-side API access with specific connection and source grants. * **SPA OAuth Clients** — Single Page Application authentication flows. * **M2M OAuth Clients** — Machine-to-Machine authentication flows. ## `carto credentials list [type]` List credentials, optionally filtered by type. ```bash carto credentials list # All credentials carto credentials list tokens # Only API tokens carto credentials list spa # Only SPA OAuth clients carto credentials list m2m # Only M2M OAuth clients ``` ## `carto credentials create token` Create an API Access Token. A token can be scoped to one or more `(connection, source)` pairs and an explicit list of allowed APIs. ```bash # Single fully-qualified source carto credentials create token \ --connection carto_dw \ --source "carto.shared.demo_table" \ --apis sql,maps # Wildcard pattern (note: minimum two dot-separated segments before the wildcard) carto credentials create token \ --connection carto_dw \ --source "carto.shared.CARTO_*" \ --apis sql,maps # All sources on a connection, with expiry and a label carto credentials create token \ --connection carto_dw \ --source "*" \ --apis sql,maps \ --name "demo-day-token" \ --expiration-date 7d ``` **Options:** | Option | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--connection ` | Connection to grant. Repeat alongside every `--source` to grant multiple connections in one token. | | `--source ` | Fully-qualified table/tileset/query, a wildcard pattern like `"carto.shared.CARTO_*"` (minimum two dot-separated segments), or `"*"` for all sources on the connection. | | `--apis ` | Comma-separated API list: `sql`, `maps`, `imports`, `exports`, `lds`. `carto export` requires the `exports` scope. | | `--referer ` | Allowed referer URL. | | `--name ` | Optional token label (auto-generated if omitted). | | `--expiration-date ` | Optional expiry. ISO date (`2027-01-01`) or shorthand (`1d`, `2w`, `6m`, `1y`). Tokens never expire if omitted. | ## `carto credentials create spa` Create a SPA (Single Page Application) OAuth Client. ```bash carto credentials create spa \ --title "My Web App" \ --callback "https://myapp.com/callback" \ --logout-url "https://myapp.com/logout" \ --web-origin "https://myapp.com" \ --allowed-origin "https://myapp.com" ``` **Options:** | Option | Description | | ------------------------ | ----------------------------- | | `--title ` | Application title (required). | | `--login-uri ` | Login initiation URI. | | `--callback ` | OAuth callback URL. | | `--logout-url ` | Logout redirect URL. | | `--web-origin ` | Web origin URL. | | `--allowed-origin ` | Allowed CORS origin. | ## `carto credentials create m2m` Create a Machine-to-Machine OAuth Client. ```bash carto credentials create m2m --title "Backend Service" ``` **Options:** | Option | Description | | ---------------- | ----------------------------- | | `--title ` | Application title (required). | ## `carto credentials get ` Get details for a specific credential. ```bash carto credentials get token carto credentials get spa carto credentials get m2m ``` ## `carto credentials update ` Update a credential in place. For an API Access Token the token value does not change, so deployed applications keep working while you add grants or APIs. ```bash # Add a grant on a table, or on a SQL query (commas inside the SQL are kept) carto credentials update token --add-grant "carto_dw,carto.shared.demo_table" carto credentials update token --add-grant "carto_dw,SELECT id, name FROM carto.shared.demo_table" # The same, as separate flags carto credentials update token --connection carto_dw --source "carto.shared.CARTO_*" # Allow another API, or replace the referers carto credentials update token --add-api maps carto credentials update token --referers "https://app.example.com,https://staging.example.com" carto credentials update spa --title "Updated Title" ``` **Options (tokens):** | Option | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--add-grant ` | Append a grant as `","`. Only the first comma separates the pair, so a SQL source may contain commas. Pass `"*"` as the source to grant every source on the connection. | | `--connection ` | Connection for a new grant. Use together with `--source`. | | `--source ` | Source for the new grant: a table, tileset or query, a wildcard pattern, or `"*"`. | | `--add-api ` | Append an allowed API: `sql`, `maps`, `imports`, `exports` or `lds`. | | `--referers ` | Replace the allowed referers with this comma-separated list. | | `--json-body ` | Replace the whole credential body with this JSON. Read the current body first with `credentials get`. | ## `carto credentials delete ` Delete a credential. `revoke` is an alias for `delete` on M2M clients. ```bash carto credentials delete token carto credentials delete spa carto credentials revoke m2m ``` # maps Manage CARTO Builder maps. Create, edit, validate, publish, copy across organizations, screenshot, and inspect the agent surface. ```bash carto maps list [options] # List maps carto maps get # Pretty details; --json emits round-trippable JSON carto maps create [json] # Create from JSON (positional, path, or stdin) carto maps update [json] # Update (partial JSON OK) carto maps validate [json] # Tier-1 preflight (offline, no API calls) carto maps verify-remote [json] # Tier-0 + Tier-2 (validate + warehouse dry-runs) carto maps publish # Freeze a snapshot so viewers see current state carto maps schema [section] # JSON Schema reference for agents carto maps agents # AI agent introspection (see below) carto maps datasets update

# PATCH a single dataset on an existing map carto maps screenshot [options] # Save a PNG screenshot (opt-in Chromium) carto maps copy --dest-profile # Duplicate (cross-org or same org) carto maps delete # Delete map ``` ## The bundle model `maps get --json` returns a **round-trippable bundle** — the same shape that `maps create` and `maps update` accept. Server-computed fields are stripped, privacy is synthesised from top-level fields, and datasets are inlined. You can pipe the output straight back in: ```bash carto maps get abc123 --json > map.json jq '.title = "New title"' map.json | carto maps update abc123 ``` Bundle input accepts a positional JSON string, a filesystem path, or stdin: ```bash carto maps create '{"title":"…", "connectionId":"…"}' # Inline JSON carto maps create ./map.json # Path carto maps create < map.json # Stdin ``` Pre-flight validation (Tier-1 schema checks, source SQL dry-run, privacy coercion, agent model auto-fill, `aggregationExp` auto-fill for spatial-index datasets on supported providers) runs before any write — broken bundles reject without creating an orphan map. Post-write verification surfaces as warnings in the JSON output. For the full bundle recipe (including authoring patterns and the agent skill that drives it), see the [`carto-create-builder-maps`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-builder-maps) skill. ## Two-version model Private editing mutates the live map via `PATCH /maps/:id`. **Shared and public viewers** read from a frozen snapshot created by `POST /maps/:id/publish`. Setting `privacy=shared` or `privacy=public` puts the map in dashboards, but viewers see the prior snapshot (or nothing if never published). Use `carto maps publish ` to update the snapshot — or pass `--publish` to `maps update` to chain both. `create` and `update` emit an `UNPUBLISHED_SHARED_MAP` warning when privacy is `shared`/`public` but no snapshot exists. ## `carto maps list` | Option | Description | | -------------------------------- | ----------------------------------------------------- | | `--mine` | Show only your maps. | | `--search ` | Free-text search across title/description. | | `--privacy ` | Filter by privacy: `private`, `shared`, `public`. | | `--tags ` | Filter by tags (JSON array, e.g. `'["demo","poc"]'`). | | `--order-by ` | Sort by `updatedAt`, `createdAt`, `title`. | | `--order-direction ` | `ASC` or `DESC`. | | `--page ` / `--page-size ` | Pagination. | | `--all` | Fetch all pages automatically. | ## `carto maps create` / `carto maps update` | Option | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `--dry-run` | (`update`) Print planned actions without writing. | | `--datasets-mode replace` | (`update`) Delete datasets not mentioned in the input (default: merge). | | `--publish` | (`update`) Chain `maps publish ` after the update succeeds. | | `--allow-kepler-replace` | Allow wholesale `keplerMapConfig` partial-update replacement (use the read-modify-write cycle instead unless you know what you're doing). | The response includes `builderUrl`, `viewerUrl`, and `publicUrl` as first-class fields. `mapUrl` is kept as a back-compat alias for `builderUrl` and will be dropped on the next major. ## `carto maps validate` / `carto maps verify-remote` * `maps validate` — **Tier-1 only**, offline, no API calls. Same input surface as `create`. Exits 1 on any issue. Use to iterate on a bundle before writing. * `maps verify-remote` — Tier-1 + Tier-2 (warehouse-side checks: source dry-runs, region match, region-aware SQL). Reads credentials but never calls `POST /maps`. Useful before shipping a bundle in CI. ## `carto maps publish` Freeze a snapshot so shared/public viewers see the current state: ```bash carto maps publish abc123 # Or chain it onto an update: carto maps update abc123 < map.json --publish ``` Snapshots are versioned; the platform tracks `lastPublishedAt` per map. Republishing replaces the prior snapshot. ## `carto maps schema [section]` JSON Schema reference for agents authoring bundles. Sections include `bundle`, `dataset`, `layer.tileset`, `layer.h3`, `layer.quadbin`, `layer.heatmapTile`, `layer.clusterTile`, `layer.raster`, `widgets`, `widgetspanellayout`, `sqlparameters`, `popupsettings`, `privacy`, `agent`, `enums`, `mapstate`, `mapstyle`, `mapsettings`, `uistate`, `legendsettings`. ```bash carto maps schema layer.h3 carto maps schema uistate ``` {% hint style="info" %} **Scale-with-zoom-level radius (tileset point layers)**: `maps schema layer.tileset` includes four optional `visConfig` fields enabling Builder's third Radius mode — alongside Fixed and a column field: `maps validate` rejects two shapes that would silently break in Builder: `radiusScaleWithZoom: true` without a `radius` value (renders zero-pixel points at the reference zoom), and `radiusScaleWithZoom: true` alongside a `radiusField` (mutually exclusive Radius modes). {% endhint %} | Field | Type | Notes | | --------------------- | ---------------- | --------------------------------------------- | | `radiusScaleWithZoom` | `boolean` | Enables the mode. | | `radiusReferenceZoom` | `number` (0–22) | Zoom level at which `radius` is rendered 1:1. | | `sizeMinPixels` | `number` (1–100) | Lower clamp as the user zooms out. | | `sizeMaxPixels` | `number` (1–100) | Upper clamp as the user zooms in. | ## `carto maps agents` Discover the AI surface available on the current tenant: ```bash carto maps agents status # Is CARTO AI enabled? What's the default model? carto maps agents models # AI models you can put in agent.config.model (formatted "{source}::{provider}::{model}") carto maps agents mcp-tools # MCP tools (workflow-backed) available for agent.config.tools[] carto maps agents core-tools # Hardcoded core Builder tools and their activation rules ``` Call `maps agents status` before emitting an `agent` block in a bundle — bundles authored for tenants with CARTO AI disabled get the `agent` block stripped with a warning. ## `carto maps datasets update` PATCH a single dataset on an existing map without re-emitting the full bundle. Used to swap the SQL, columns, or aggregation of one source while leaving the rest of the map alone. ```bash carto maps datasets update

'{"source":"SELECT … FROM new_table"}' ``` ## `carto maps copy` Duplicate a map between profiles (organizations). Connections are mapped automatically by name; supply explicit mappings for renamed cases. ```bash # Auto-map connections by name (default) carto maps copy --dest-profile production # Manual mapping for renamed connections carto maps copy --dest-profile prod \ --connection-mapping "dev-bq=prod-bq,dev-sf=prod-sf" # Override source profile and title carto maps copy --source-profile staging --dest-profile prod \ --title "Production Map" ``` | Option | Description | | ---------------------------- | ----------------------------------------------------------------------------------- | | `--dest-profile ` | (Required) Destination profile name. | | `--source-profile ` | Source profile (default: current). | | `--connection-mapping ` | Per-source map (e.g. `"src1=dst1,src2=dst2"`). Preferred for multi-connection maps. | | `--connection ` | Legacy: single connection for all datasets. | | `--title ` | Override the map title in the destination. | | `--skip-source-validation` | Skip validating that destination connections can read source tables/queries. | | `--keep-privacy` | Preserve privacy setting from source (default: true). | For a full walkthrough including connection-mapping scenarios and troubleshooting, see [Examples → Copying maps and workflows between organizations](/carto-for-agents/cli/examples#copying-maps-and-workflows-between-organizations). ## `carto maps screenshot` {% hint style="info" %} `carto maps screenshot` is **experimental**. Its flags, render engines, and output may change in future releases. {% endhint %} Render a PNG of the map. Two render engines: * **`light`** (default) — a bundled minimal viewer (`@deck.gl/carto` `fetchMap`). \~2.5 MB asset, \~8 s cold start, \~10 MB network. Renders layers + basemap. **No widgets, legends, popups, or chrome.** * **`full`** — the full CARTO Builder viewer at `/viewer/:mapId` rendered in a headless iframe. \~20 s, \~28 MB. Full feature parity. ```bash carto maps screenshot abc123 -o map.png carto maps screenshot abc123 --lat 40.42 --lng -3.70 --zoom 12 --hide-overlays carto maps screenshot abc123 --render-engine full ``` | Option | Description | | -------------------------------------------------- | ----------------------------------------------------- | | `--render-engine <e>` | `light` (default) or `full`. | | `-o, --output <path>` | Output file path (default: `screenshot.png`). | | `--width <px>` / `--height <px>` | Viewport size (default: 1280 × 800). | | `--lat <deg>` / `--lng <deg>` | Center coordinates. | | `--zoom <n>` / `--bearing <deg>` / `--pitch <deg>` | Viewport. | | `--layers <indices>` | Comma-separated visible layer indices (e.g. `"0,2"`). | | `--search <query>` | Address or `"lat,lng"` to center on. | | `--hide-overlays` | Hide CARTO logo, attribution, zoom controls, legend. | | `--wait <seconds>` | Optional pad after auto-detected render (default: 0). | | `--timeout <seconds>` | Navigation/render timeout (default: 60). | | `--full-page` | Capture full scrollable page instead of viewport. | | `--no-cache` | Bypass persistent Chromium profile (`full` engine). | {% hint style="info" %} **Optional Playwright install.** `maps screenshot` launches a headless Chromium. The browser is an opt-in dependency to keep the CLI install small: ```bash npm install playwright-core npx playwright install chromium # ~300 MB ``` The screenshot authenticates as the current CLI user, so it works on private, shared, and public maps you have access to. {% endhint %} ## `carto maps delete` ```bash carto maps delete <map-id> carto maps delete <map-id> --yes # Skip confirmation ``` ## Examples ```bash # Create from a bundle file carto maps create < map.json # Round-trip: get → edit → update carto maps get abc123 --json > /tmp/map.json jq '.title = "Q3 Dashboard"' /tmp/map.json | carto maps update abc123 # Validate locally (no network), then create carto maps validate < map.json && carto maps create < map.json # Update + publish in one go carto maps update abc123 < shared.json --publish # Agent introspection carto maps agents status carto maps schema layer.h3 ``` # workflows Manage CARTO Workflows — list, inspect, create, update, copy, validate, verify-remote, run, share, schedule, publish as MCP tools, and install extensions. ```bash carto workflows list [options] # List workflows carto workflows get <id> # Pretty details; --json = round-trippable bundle carto workflows create [--file <bundle.json>] # Create from a bundle carto workflows update <id> [--file <bundle.json>] # Update (partial bundles OK) carto workflows delete <id> # Delete workflow carto workflows copy <id> --dest-profile <name> # Duplicate (cross-tenant or same-tenant) carto workflows schema [section] # JSON Schema reference for agents carto workflows validate [--file <bundle.json>] # Tier-0 offline (Zod-only) bundle check carto workflows verify-remote <id|--file …> --connection <c> # Tier-0 + Tier-2 deep validation against a warehouse carto workflows to-sql [--file <bundle.json>] # Compile bundle → SQL preview (what `run` would submit) carto workflows components list # Agent-facing component catalog carto workflows components get <names> # Full input/output signature for components carto workflows run <id> # Execute workflow; returns per-node outputs carto workflows run output <id> <node-id> # Fetch a node's output rows carto workflows run status <job-id> # Poll an async-submitted run carto workflows share <id> [--org | --with <email>] # Share workflow carto workflows unshare <id> # Revert to private carto workflows mcp publish|unpublish|describe|list # MCP tool lifecycle carto workflows schedule add|update|remove <id> # Warehouse cron lifecycle carto workflows extensions install --file <ext.zip> --connection <name> # Install an extension zip ``` ## The bundle model `workflows get <id> --json` returns a **round-trippable bundle** (title and description lifted, server fields stripped, privacy synthesised). Pipe straight back into `workflows create --file` or `workflows update --file`: ```bash carto workflows get abc123 --json > /tmp/wf.json jq '.title = "New title"' /tmp/wf.json | carto workflows update abc123 --file - ``` Structural validation runs on Zod schemas under `src/schemas/workflows/`. For the full bundle recipe, see the [`carto-create-workflow`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-workflow) skill. {% hint style="info" %} **GeoJSON inputs**: `native.tablefromgeojson` and `native.drawcustomgeographies` accept both a stringified `FeatureCollection` and a `FeatureCollection` object on the input `value` field, so workflows that ingest GeoJSON can be authored from the CLI. {% endhint %} ## `carto workflows list` | Option | Description | | -------------------------------- | -------------------------------------------------------------------------------------- | | `--page <n>` / `--page-size <n>` | Pagination. | | `--order-by <field>` | `updated_at` (default), `created_at`, `title`. Aliases `updated` / `created` accepted. | | `--order-direction <dir>` | `ASC` or `DESC`. | | `--search <term>` | Search filter. | | `--privacy <level>` | Filter by privacy: `public` or `shared`. | | `--tags <json>` | Filter by tags (JSON array). | | `--all` | Fetch all pages automatically. | ## `carto workflows create` / `carto workflows update` | Option | Description | | ------------------------------ | ----------------------------------------------------------------------------- | | `--file <path>` | Read bundle JSON from a file (or stdin via `-`). | | `--verify` | Run Tier-2 checks (sources region + SQL dry-run + engine compile) post-write. | | `--verify sources,sql,compile` | Subset — each can also be used alone. | ```bash # Create from a bundle carto workflows create --file my-pipeline.json # Update + verify post-write carto workflows update abc123 --file pipeline.json --verify ``` ## `carto workflows validate` / `carto workflows verify-remote` * **`validate`** — **Zod-only**, offline, no network. Use it to iterate on a bundle locally before writing. The `--connection` and `--no-engine` flags are removed; for warehouse-aware validation use `verify-remote`. * **`verify-remote`** — Standalone command, hard-errors without a connection. Runs the full Tier-0/1/2 stack (structural + engine compile + schema trace + sources + customsql) without writing the workflow. Useful before opening a PR that ships a new bundle. Advisory warnings appear in the output but no longer fail the exit code; pass `--strict` to restore the previous behaviour, where any warning fails the run. ```bash # Offline structural check carto workflows validate --file bundle.json # Full warehouse-side check carto workflows verify-remote --file bundle.json --connection carto_dw # Same, but fail on advisory warnings (CI gates) carto workflows verify-remote --file bundle.json --connection carto_dw --strict ``` | Option | Description | | --------------------------- | -------------------------------------------------------------------------------------- | | `--file <path>` | Bundle JSON path (or pipe via stdin). | | `--connection <name\|uuid>` | (Required for `verify-remote`) Override `bundle.connectionId`. | | `--mode <create\|update>` | (`validate` only) Validation mode (default: `update`). | | `--strict` | (`verify-remote` only) Fail the exit code on any advisory warning, not just on errors. | ## `carto workflows to-sql` Compile a bundle to the SQL that `run` would submit, without executing: ```bash carto workflows to-sql --file bundle.json ``` ## `carto workflows components` Agent-facing component catalog. Use `list` to discover components, `get` to fetch their full input/output signatures. ```bash # Browse native components carto workflows components list --connection carto_dw --group Joins # Full signatures (for agent composition) carto workflows components get native.customsql,native.joinv2 --connection carto_dw --json # Include input-format reference entries carto workflows components get native.customsql --connection carto_dw --input-formats ``` | Option | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `--connection <name\|uuid>` | (Required) Catalog is fetched per-connection so extensions and stored procedures appear alongside native components. Provider is inferred. | | `--group <name>` | Filter `list` to a specific group (e.g. `Joins`). | | `--search <term>` | Substring match across name / title / description. | | `--starred` | Only starred components. | | `--include-deprecated` | Include deprecated components (hidden by default). | | `--input-formats` | (`get` only) Include deduped format reference entries for all input/output types. | {% hint style="warning" %} **Breaking in 0.7:** `components list` and `components get` now require `--connection`. The previous `--provider` flag was removed; the provider is now inferred from the connection so extensions and stored procedures appear in the catalog. Extension and stored-procedure load failures surface as warnings (in JSON output under a `warnings` array; in text as `Warning: …` lines). {% endhint %} For `Selection`-typed inputs (e.g. `native.isolines.mode`) the JSON output includes both `options` (the wire values the engine accepts, e.g. `"walk"`) and `optionsText` (the matching human-readable labels, e.g. `"Walk"`). Use `options` when populating the bundle. ## `carto workflows run` Execute a workflow and fetch results: ```bash carto workflows run <id> # Run synchronously; returns per-node outputs carto workflows run <id> --async # Return immediately with a job ID carto workflows run status <job-id> # Poll the async job carto workflows run output <id> <node-id> # Fetch a specific node's output rows ``` ## `carto workflows share` / `carto workflows unshare` Identify users by email with `--with`. The CLI resolves each email to a user ID, so a typo fails loudly rather than sharing with the wrong person. ```bash # Share with the whole organization carto workflows share <id> --org # Share with a specific user by email carto workflows share <id> --with someone@example.com # Repeat or comma-separate to reach several people at once carto workflows share <id> --with a@example.com --with b@example.com carto workflows share <id> --with a@example.com,b@example.com # Also grant edit access, and see who has access today carto workflows share <id> --with someone@example.com --can-edit carto workflows share <id> --list # Remove one person's access, or revert to private carto workflows unshare <id> --with someone@example.com carto workflows unshare <id> ``` **Options:** | Option | Description | | ---------------- | ---------------------------------------------------------------------- | | `--org` | Share with the entire organization (`unshare` drops org-wide sharing). | | `--with <email>` | Share with a user by email. Repeatable, or comma-separated. | | `--can-edit` | Grant edit access as well as read (`share` only). | | `--list` | Show the current sharing state without changing it (`share` only). | {% hint style="info" %} `--user-id` and `--user-email` were removed in v0.10.0. Use `--with <email>`. {% endhint %} ## `carto workflows mcp` Publish a workflow as an MCP tool so it shows up in the CARTO MCP Server: ```bash carto workflows mcp publish <id> [options] # Expose this workflow as an MCP tool carto workflows mcp unpublish <id> # Remove from MCP catalog carto workflows mcp describe <id> # Show current MCP tool registration carto workflows mcp list # List all workflows published as MCP tools ``` Workflows on Redshift and Oracle connections always publish as Async tools. A publish that requests Sync execution on these connections is rejected with an error explaining why. See the [Workflows as MCP Tools](/carto-user-manual/workflows/workflows-as-mcp-tools) guide for the publishing flow end-to-end. ## `carto workflows schedule` Warehouse-side cron lifecycle for the workflow's run schedule: ```bash carto workflows schedule add <id> --cron "0 6 * * *" carto workflows schedule update <id> --cron "0 6 * * 1-5" carto workflows schedule remove <id> ``` ## `carto workflows copy` Duplicate a workflow between profiles. Connection mapping behaves like `maps copy`. ```bash # Auto-map by name carto workflows copy abc123 --dest-profile production # Explicit connection carto workflows copy abc123 \ --source-profile staging \ --dest-profile production \ --connection prod-bigquery ``` | Option | Description | | ---------------------------- | ----------------------------------------------------------- | | `--dest-profile <name>` | (Required) Destination profile name. | | `--source-profile <name>` | Source profile (default: current). | | `--connection <name>` | Destination connection name (auto-maps by name if omitted). | | `--connection-mapping <map>` | Per-source map: `"src1=dst1,src2=dst2"`. | | `--title <title>` | Override workflow title in the destination. | | `--skip-source-validation` | Skip validating source table accessibility. | For the full walkthrough including connection-mapping scenarios, see [Examples → Copying maps and workflows between organizations](/carto-for-agents/cli/examples#copying-maps-and-workflows-between-organizations). ## `carto workflows extensions install` Install a CARTO Workflows extension zip (bundles `metadata.json` + provider-specific SQL) into a warehouse connection. ```bash carto workflows extensions install --file my-extension.zip --connection carto_dw ``` | Option | Description | | --------------------- | ------------------------------------------------------------------------- | | `--file <path>` | (Required) Path to the extension `.zip`. | | `--connection <name>` | (Required) Connection to install into. Provider must match the extension. | ## Examples ```bash # List ETL workflows, recently updated first carto workflows list --search "ETL" --order-by updated_at # Round-trip get → edit → update carto workflows get abc123 --json > /tmp/w.json jq '.title = "New title"' /tmp/w.json | carto workflows update abc123 --file - # Local validation before write carto workflows validate --file bundle.json # Full warehouse-side verification before merging a bundle PR carto workflows verify-remote --file bundle.json --connection carto_dw # Preview the SQL `run` would submit carto workflows to-sql --file bundle.json # Publish as MCP tool so agents can call it carto workflows mcp publish abc123 ``` # projects Manage CARTO projects — the containers that group maps and workflows. A project is a top-level folder; it can hold subfolders, native maps and workflows, and shortcuts to maps or workflows that live elsewhere. ```bash # Read carto projects list [options] # Top-level projects carto projects get <id|name> # Project details + full contents tree # Top-level CRUD carto projects create --name <name> # New top-level project carto projects rename <path> --to <name> # Rename a folder carto projects delete <path> # Delete a folder or shortcut # Asset placement carto projects add <path> --folder <name> # Create a subfolder inside a project carto projects add <path> --map <map-id> # Add an existing map (creates a shortcut) carto projects add <path> --workflow <wf-id> # Add an existing workflow (creates a shortcut) carto projects move <path> --to <path> # Move a folder or shortcut to a new parent # Local-sync workflow carto projects init <name> # New project + scaffold a local working dir carto projects clone <id|name> # Materialize an existing project to disk carto projects status # Show local-vs-clone diff (run inside a checkout) ``` ## Identifier resolution Project arguments accept **either** the UUID (e.g. `62c90ed4-eeec-46d0-bda9-c7ea173e26f0`) or the project name. Names are resolved via the entries search; ambiguous matches error out and ask for the UUID. Nested locations use **slash paths**: `Q2 Analytics/Maps/Drafts`. The first segment must be a top-level project (or its UUID); subsequent segments walk the tree by title-match within each parent folder. ## Adding maps and workflows: shortcuts under the hood The CARTO platform doesn't currently expose a way to move an existing map or workflow into a folder — assets live at the account root. The mechanism for making one appear inside a project is to create a **shortcut** (an alias entry pointing at the underlying asset). `carto projects add <path> --map <id>` creates that shortcut for you. The map itself is not moved; deleting the shortcut later only removes the alias, not the map. ## Local-sync workflow Treat a CARTO project as a working directory you can clone, edit, and sync: ```bash # Start a brand-new project — creates server-side and scaffolds a local dir carto projects init "Q2 Analytics" --color "#3478f6" cd q2-analytics $EDITOR AGENTS.md # capture project context for an agent # Or check out an existing project carto projects clone "Q2 Analytics" cd q2-analytics ls -R # AGENTS.md, README.md, *.map.json, *.workflow.json # See what's changed locally vs the clone carto projects status # Optionally check whether anything moved on the server since you cloned carto projects status --server ``` The clone lays down: * `.carto/project.json` — manifest with project ID, content hashes, server timestamps, and the recursive entry tree. * `AGENTS.md`, `README.md` — tracked scaffold docs (their hashes go in the manifest, so edits show up in `status`). * `.gitignore` — meta, untracked. * For each entry: a directory (folders) or a `*.map.json` / `*.workflow.json` bundle. Pushing edits back uses the existing per-resource verbs: ```bash $EDITOR my-map.map.json carto maps update <map-id> < my-map.map.json ``` ## Common flags **`projects list`** — `--in <id|name>`, `--search <query>`, `--owner <me|others>`, `--mine`, `--order-by <field>` (`updatedAt` / `title`), `--order-direction <ASC|DESC>`, `--page`, `--page-size`. **`projects get`** — `--depth <n>` (0 = unbounded, 1 = top level only), `--budget <n>` (folder-lookup cap, default 500), `--no-entries` (metadata only). **`projects create`** — `--name <name>`, `--color <hex>`, `--file <path>` (read full create payload from JSON). **`projects add`** — exactly one of `--folder <name>`, `--map <map-id>`, `--workflow <id>`, plus `--color <hex>` for new subfolders. **`projects rename`** — `--to <new-name>`. **`projects move`** — `--to <path>`. Top-level → top-level is not supported by the API today. **`projects delete`** — `--yes` to skip the confirmation prompt. **`projects init`** / **`projects clone`** — `--path <dir>` (default: `./<slug-of-name>/`), `--force` (write into a non-empty dir / overwrite scaffold). `clone` adds `--shallow` (skip bundle fetches, just structure) and `--budget <n>`. **`projects status`** — `--path <dir>` (project root, defaults to walking up from CWD), `--server` (also check for changes on the CARTO server since clone). ## Examples ```bash # Browse carto projects list --mine carto projects list --search analytics carto projects get "Q2 Analytics" carto projects get "Q2 Analytics/Maps" # Build out a project carto projects create --name "Q2 Analytics" --color "#3478f6" carto projects add "Q2 Analytics" --folder "Maps" carto projects add "Q2 Analytics/Maps" --map 62c90ed4-eeec-46d0-bda9-c7ea173e26f0 carto projects add "Q2 Analytics" --workflow b32f9fff-4303-4f75-bf7a-1f661c60b53a # Reorganize carto projects rename "Q2 Analytics/Maps" --to "Production maps" carto projects move "Q2 Analytics/Production maps" --to "Q1 Archive" # Clean up carto projects delete "Q2 Analytics" --yes ``` # connections Manage data warehouse connections (BigQuery, Snowflake, Redshift, PostgreSQL, Databricks, …). ## `carto connections list` List all connections. ```bash carto connections list ``` ## `carto connections get <connection-id>` Get details for a specific connection. The output includes a `Shared with:` line listing the organization, users and groups that can use it. ```bash carto connections get conn_xyz789 ``` ## `carto connections create <json-body>` Create a new connection. The body's shape depends on the provider. ```bash carto connections create '{ "name": "my-snowflake", "type": "snowflake", "parameters": { "account": "myaccount", "warehouse": "compute_wh" } }' ``` ## `carto connections update <connection-id> <json-body>` Update a connection. ```bash carto connections update conn_xyz789 '{ "parameters": { "warehouse": "new_wh" } }' ``` ## `carto connections delete <connection-id>` Delete a connection. ```bash carto connections delete conn_xyz789 ``` ## `carto connections share` / `carto connections unshare` Control who can use a connection: the whole organization, specific users, or groups. Identify users by email with `--with` and groups by name or id with `--group`. The CLI resolves both before changing anything, so a typo fails loudly instead of sharing with the wrong person. New grants are added to the access the connection already has; use `unshare` to take access back. The connection can be given by id or by name. ```bash # Share with the whole organization carto connections share my-conn --org # Share with specific users, and with a group carto connections share my-conn --with a@example.com,b@example.com --group Analysts # See who has access today, without changing anything carto connections share my-conn --list # Remove one person's access, or revert to owner-only carto connections unshare my-conn --with a@example.com carto connections unshare my-conn ``` **Options:** | Option | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------ | | `--org` | Share with the entire organization (`unshare` drops organization-wide access and keeps specific users and groups). | | `--with <email>` | Share with a user by email. Repeatable, or comma-separated. | | `--group <name>` | Share with a group by its name or id. Repeatable, or comma-separated. | | `--list` | Show the current sharing state without changing it (`share` only). | People you share with use the connection under its owner's credentials, unless the connection requires viewer credentials. Organization Admins can turn connection sharing off for the whole organization, in which case `share` is refused. See [Sharing a connection](/carto-user-manual/connections/sharing-a-connection) in the user manual for how sharing behaves in CARTO. {% hint style="info" %} Sharing a connection with specific users or groups needs a CARTO platform that supports connection access policies. On an older Self-hosted deployment the command stops with an upgrade message before changing anything. {% endhint %} ## `carto connections browse <name> [path]` Browse the resource tree exposed by a connection (databases, schemas, tables, tilesets). Useful for picking source paths when authoring maps or workflows without leaving the terminal. ```bash # Top-level tree for a connection carto connections browse carto_dw # Drill into a specific subtree carto connections browse carto_dw "carto-demo-data" ``` **Options:** | Option | Description | | -------------------- | ---------------------------------------------------------- | | `--depth <n>` | Max tree depth to expand (default: server default). | | `--max-items <n>` | Max total items to return (default: server default of 30). | | `--max-children <n>` | Max children per node (default: server default). | ## `carto connections describe <name> <table-path>` Get the schema and details for a single table on a connection (column names, types, partitioning, row count when available). ```bash carto connections describe carto_dw "carto-demo-data.demo_tables.nyc_collisions" ``` ## `carto connections search <name> <query>` Free-text search across the tables and views reachable through a connection. ```bash carto connections search my-conn "customers" carto connections search my-conn "orders" --scope "mydb.public" --type table ``` **Options:** | Option | Description | | --------------- | ------------------------------------------------------ | | `--type <kind>` | Filter by resource type: `table` or `view`. | | `--limit <n>` | Max results, 1–100 (default: 20). | | `--scope <fqn>` | Narrow the search to a subtree (e.g. `"mydb.public"`). | # named-sources Manage **Named Sources** — server-side aliases for SQL queries. Instead of exposing raw SQL in client applications, create a Named Source with a name and reference it by name wherever the CARTO APIs accept a `sqlQuery` parameter. {% hint style="info" %} The Named Sources API requires **OAuth Access Tokens** (from `carto auth login`), not API Access Tokens. {% endhint %} ```bash carto named-sources list # List named sources carto named-sources get <name> # Get named source details carto named-sources create --name <n> --source <sql> # Create named source carto named-sources update <name> --source <sql> # Update named source carto named-sources delete <name> # Delete named source ``` ## `carto named-sources list` | Option | Description | | ------------------ | ----------------------------- | | `--page-size <n>` | Items per page (default: 10). | | `--page <n>` | Page number (default: 1). | | `--search <query>` | Search named sources by text. | ## `carto named-sources create` | Option | Description | | ---------------- | -------------------------------------------------------------------------------- | | `--name <name>` | Source name (3–50 chars, lowercase letters/numbers, dashes/underscores allowed). | | `--source <sql>` | SQL query for the named source. | ## Examples ```bash # List all named sources carto named-sources list # Search named sources carto named-sources list --search "my_source" # Create a named source carto named-sources create --name my_source --source "SELECT * FROM project.dataset.table" # Get details carto named-sources get my_source # Update the SQL query carto named-sources update my_source --source "SELECT id, geom FROM project.dataset.table" # Delete (with confirmation) carto named-sources delete my_source # Delete (skip confirmation for CI/CD) carto named-sources delete my_source --yes ``` # do (Data Observatory) Browse, search, and subscribe to datasets from the CARTO Data Observatory catalog (10,000+ spatial datasets from 50+ providers). ```bash # Discover available filters (countries, categories, providers, licenses, etc.) carto do filters # All filter values with dataset counts carto do filters --json | jq '.categories' # Just categories (programmatic) # Browse and search carto do list --category demographics # Browse datasets by category carto do list --country usa --limit 10 # Browse by country carto do list --provider experian # Browse by provider carto do list --license public # Filter by license type carto do search "demographics united states" # Full-text search carto do search "flood risk" --license public # Search with filters # AI-powered semantic variable search (requires embeddings) carto do search-variables "purchasing power" --country deu carto do search-variables "population density" --limit 10 # Dataset details carto do details <dataset-id> # Full dataset metadata carto do sample <dataset-id> # Data sample + data dictionary # Subscriptions (public datasets only — premium requires contacting sales) carto do subscriptions # List your subscriptions carto do subscribe <dataset-id> # Subscribe using catalog slug carto do subscribe wp_population_29d72d59 # Resolves slug → creates BQ view carto do subscribe <id> --filter "WHERE country_iso = 'US'" # Partial subscription carto do subscribe <id> --columns "geoid, population, geom" # Specific columns only carto do subscribe <id> --connection my-sf --destination db.tbl # Subscribe + transfer carto do unsubscribe <dataset-id> # Remove a subscription carto do unsubscribe <dataset-id> --yes # Skip confirmation ``` ## `carto do list` / `carto do search` | Option | Description | | -------------------- | ---------------------------------------------------------- | | `--category <name>` | Filter by category (e.g. `Demographics`, `Environmental`). | | `--provider <name>` | Filter by provider (e.g. `Experian`, `TomTom`). | | `--country <name>` | Filter by country. | | `--license <type>` | Filter: `premium` or `public`. | | `--limit <n>` | Results per page (default: 20). | | `--page <n>` | Page number (default: 1). | | `--order-by <field>` | Order: `popular`, `recent`, `alphabetical` (list only). | ## `carto do subscribe` | Option | Description | | ----------------------- | ---------------------------------------------------------------------- | | `--filter <where>` | SQL `WHERE` clause to filter data (e.g. `"WHERE country_iso = 'US'"`). | | `--columns <cols>` | Comma-separated columns to include (default: all). | | `--connection <name>` | Transfer data to this connection after subscribing. | | `--destination <table>` | Destination table (required with `--connection`). | # import Import a geospatial file into your data warehouse from a local file or URL. Waits for completion by default. **Supported formats:** CSV, GeoJSON, GeoPackage, GeoParquet, KML, KMZ, TAB, Shapefile (zip).\ **Size limit:** 5 GB per file.\ **Supported warehouses:** CARTO DW, BigQuery, Snowflake, PostgreSQL, Redshift, Databricks, Oracle. ```bash carto import --file <path> --connection <name> --destination <table> carto import --url <url> --connection <name> --destination <table> carto import status <jobId> # Fetch status of an async import job ``` An import that finished but lost rows ends with the status `completed_with_warnings`. The table exists and the CLI exits successfully, printing how many rows were dropped and why: rows without a readable location are in the table without geometry, rows with formatting errors were not imported. With `--json`, the counts are in `metadata.droppedRows`, `metadata.droppedRowReasons` and `metadata.droppedRowsByReason`. ## Options | Option | Description | | --------------------- | ------------------------------------------------------------------------ | | `--file <path>` | Local file to upload (mutually exclusive with `--url`). | | `--url <url>` | Remote file URL to import (mutually exclusive with `--file`). | | `--connection <name>` | (Required) Connection name. | | `--destination <fqn>` | (Required) Fully qualified table name. | | `--overwrite` | Overwrite an existing table (default: false). | | `--no-autoguessing` | Disable automatic column type detection (default: autoguessing enabled). | | `--async` | Return immediately with the job ID instead of polling to completion. | ## Examples ```bash # Import local CSV carto import --file ./data.csv --connection carto_dw --destination project.dataset.my_table # Import from URL with overwrite carto import \ --url https://example.com/data.geojson \ --connection carto_dw \ --destination project.dataset.table \ --overwrite # Kick off async, then poll status separately carto import --file ./big.csv --connection carto_dw --destination my.table --async carto import status <jobId> # JSON output (for scripts) carto import --file ./data.geojson --connection carto_dw --destination project.dataset.table --json ``` ## CSV auto-detection For CSV files, CARTO automatically detects geometry columns or builds geometries from lat/lon columns: * **Geometry columns:** `geom`, `Geom`, `geometry`, `the_geom`, `wkt`, `wkb`. * **Latitude columns:** `latitude`, `lat`, `Latitude`. * **Longitude columns:** `longitude`, `lon`, `Lon`, `Longitude`, `lng`, `Lng`. Disable with `--no-autoguessing` if you need full control over the schema. # export Export a warehouse table to a file. Returns a download URL (24 h expiry) or writes to cloud storage. **Formats:** `geoparquet`, `geojson`, `shapefile`, `csv`, `geopackage`, `kml`, `kmz`, `tab`. ```bash carto export --connection <name> --source <table> --format <fmt> carto export status <jobId> # Fetch status of an async export job ``` ## Options | Option | Description | | --------------------- | ---------------------------------------------------- | | `--connection <name>` | (Required) Connection name. | | `--source <fqn>` | (Required) Source table name. | | `--format <fmt>` | (Required) Output format. | | `--select <cols>` | Comma-separated columns to project (default: all). | | `--where <predicate>` | Warehouse-native SQL predicate (no leading `WHERE`). | | `--limit <n>` | Max rows to export. | | `--dest-url <url>` | Direct cloud destination (`gs://`, `s3://`). | | `--async` | Return job ID immediately without waiting. | ## Examples ```bash # Export as GeoParquet (waits, prints download URL) carto export --connection carto_dw --source project.dataset.my_table --format geoparquet # Export selected columns with a WHERE predicate and a row limit carto export \ --connection carto_dw \ --source project.dataset.my_table \ --format csv \ --select name,lon,lat \ --where "year = 2025" \ --limit 10000 # Export directly to cloud storage carto export \ --connection carto_dw \ --source project.dataset.my_table \ --format geojson \ --dest-url gs://my-bucket/exports/data.geojson # Kick off async, then poll status separately carto export --connection carto_dw --source project.dataset.big --format csv --async carto export status <jobId> ``` # transfer Transfer data between warehouses. Waits for completion by default. ```bash carto transfer --source-connection <n> --dest-connection <n> --source-table <t> --dest-table <t> carto transfer status <jobId> # Fetch status of an async transfer job ``` {% hint style="info" %} Transfer requires the DuckDB import engine to be enabled for your account. {% endhint %} ## Options | Option | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `--source-connection <name>` | (Required) Source connection name. | | `--dest-connection <name>` | (Required) Destination connection name. | | `--source-table <fqn>` | (Required) Source table. | | `--dest-table <fqn>` | (Required) Destination table. | | `--geography` | Use geography type for spatial data. | | `--overwrite` | Replace the destination table if it already exists. The replacement is staged, so the existing table survives a failed transfer. | | `--target-srid <epsg>` | Reproject geometry to this EPSG code at the destination. Fails if the destination cannot store it. | | `--preserve-source-crs` | Keep the source CRS instead of applying the destination's convention. Fails if the destination cannot store it. | | `--async` | Return job ID immediately without waiting. | `--target-srid` and `--preserve-source-crs` are mutually exclusive. ## Examples ```bash # Transfer from BigQuery to Snowflake carto transfer \ --source-connection bigquery-prod \ --dest-connection snowflake-analytics \ --source-table project.dataset.customers \ --dest-table db.schema.customers # With geography support, async carto transfer \ --source-connection bq-prod \ --dest-connection postgres-dev \ --source-table project.dataset.geo_data \ --dest-table public.geo_data \ --geography --async # Overwrite the destination and reproject to EPSG:4326 carto transfer \ --source-connection bq-prod \ --dest-connection snowflake-analytics \ --source-table project.dataset.parcels \ --dest-table db.schema.parcels \ --overwrite --target-srid 4326 # Poll an async transfer carto transfer status <jobId> ``` # sql Run SQL on your data warehouse using existing connections. Two modes: `query` returns result rows; `job` runs DDL/DML and polls to completion without returning a result set. ## `carto sql query <connection> [sql]` Run a SQL query and return results. Queries are sent as a `POST` (no URL-length limit, 1-minute timeout). ```bash # Query argument carto sql query <connection> "SELECT * FROM dataset.table LIMIT 10" # Read SQL from a file carto sql query <connection> --file query.sql # Pipe via stdin echo "SELECT COUNT(*) FROM dataset.table" | carto sql query <connection> # Bind parameters carto sql query <connection> "SELECT * FROM t WHERE id = @id" --param id=a-001 # JSON output carto sql query <connection> "SELECT * FROM dataset.table" --json ``` **Options:** | Option | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------- | | `--file <path>` | Read SQL from a file. | | `--param <key=value>` | Bind a query parameter. Repeatable. Values are JSON-parsed (number, boolean, array), otherwise treated as a string. | | `--params-json <json>` | Bind query parameters from a JSON object or array, for full type control. Not combinable with `--param`. | ## `carto sql job <connection> [sql]` Run a DDL/DML job. Polls until complete; no timeout. Used when no result set is returned. ```bash # CREATE TABLE carto sql job <connection> "CREATE TABLE dataset.newtable AS SELECT * FROM dataset.oldtable" # INSERT carto sql job <connection> "INSERT INTO dataset.table VALUES (1, 'test')" # Read from a file carto sql job <connection> --file create_table.sql ``` **Use cases:** * `CREATE TABLE` operations. * `INSERT`, `UPDATE`, `DELETE` statements. * Long-running data transformations. * Operations that don't return result sets. ## Input methods (both `query` and `job`) 1. Command argument: `carto sql query myconn "SELECT * FROM table"`. 2. File: `carto sql query myconn --file query.sql`. 3. Stdin: `echo "SELECT * FROM table" | carto sql query myconn`. # lds CARTO Location Data Services from the terminal: geocoding, reverse geocoding, isolines, routing, and origin-destination matrices. Each subcommand uses the provider configured for your account and counts against its quota. Run [`carto lds capabilities`](#carto-lds-capabilities) to see which provider serves each operation and how much quota remains. ```bash carto lds geocode "350 5th Ave, New York, NY" carto lds reverse-geocode 40.4168 -3.7038 carto lds isolines "-3.7038,40.4168" --mode car --range 300,600 --range-type time carto lds routing "-3.7038,40.4168" "-3.6883,40.4531" --mode car carto lds od-matrix --origin "-3.70,40.41" --destination "-3.68,40.45" carto lds capabilities ``` {% hint style="info" %} Coordinates are written `lon,lat` wherever they are packed into a single value (isolines, routing, od-matrix). `reverse-geocode` is the exception: it takes `lat` and `lon` as two separate arguments. {% endhint %} Every subcommand accepts `--options <json>` for provider-specific advanced options, and `--json` for machine-readable output. ## `carto lds geocode [address...]` Geocode one or more addresses into coordinates. Pass addresses as arguments (repeat to batch them into a single request) or read them from a file with `--file`, one per line. At least one address is required, from arguments or `--file`. ```bash # Single address carto lds geocode "350 5th Ave, New York, NY" # Batch several, biased to a country carto lds geocode "Cibeles, Madrid" "Sagrada Familia, Barcelona" --country ES # From a file, one address per line, best match only carto lds geocode --file addresses.txt --limit 1 ``` | Option | Description | | ------------------ | ---------------------------------------------------------------------------- | | `--country <code>` | ISO 3166-1 country code to bias or restrict results (e.g. `US`). | | `--limit <n>` | Maximum candidates per address. | | `--file <path>` | Read addresses from a file, one per line (added to any passed as arguments). | | `--options <json>` | Provider-specific advanced options as a JSON object. | ## `carto lds reverse-geocode <lat> <lon>` Turn a coordinate into an address or place name. Latitude and longitude are separate arguments. ```bash carto lds reverse-geocode 40.4168 -3.7038 carto lds reverse-geocode 40.4168 -3.7038 --lang es --json ``` | Option | Description | | ------------------ | ----------------------------------------------------------- | | `--lang <code>` | Result language where the provider supports it (e.g. `es`). | | `--limit <n>` | Maximum candidates. | | `--options <json>` | Provider-specific advanced options as a JSON object. | ## `carto lds isolines <origin>` Compute an isoline (catchment area) around one origin, given as `lon,lat`. ```bash # 5- and 10-minute drive-time catchments carto lds isolines "-3.7038,40.4168" --mode car --range 300,600 --range-type time # 1 km walking catchment carto lds isolines "-3.7038,40.4168" --mode walk --range 1000 --range-type distance ``` | Option | Description | | --------------------- | ----------------------------------------------------------------------------------- | | `--mode <mode>` | (Required) Travel mode, provider-dependent (e.g. `car`, `walk`, `bike`). | | `--range <values>` | (Required) Comma-separated range values: seconds for `time`, meters for `distance`. | | `--range-type <type>` | (Required) Whether `--range` is `time` or `distance`. | | `--options <json>` | Provider-specific advanced options as a JSON object. | ## `carto lds routing <origin> <destination>` Compute a route between two points, each given as `lon,lat`, optionally via intermediate waypoints. ```bash carto lds routing "-3.7038,40.4168" "-3.6883,40.4531" --mode car # Via waypoints, with full geometry carto lds routing "-3.70,40.41" "-3.68,40.45" \ --mode car \ --waypoints "-3.69,40.42:-3.685,40.44" \ --overview full ``` | Option | Description | | ----------------------------- | --------------------------------------------------------------------------------- | | `--mode <mode>` | (Required) Travel mode, provider-dependent (e.g. `car`, `pedestrian`, `bicycle`). | | `--waypoints <points>` | Intermediate stops as `lon,lat:lon,lat` (colon-separated `lon,lat` pairs). | | `--overview <detail>` | Geometry detail: `simplified` (default) or `full`. | | `--simplify-tolerance <m>` | Fixed simplification tolerance in meters. Ignored with `--overview full`. | | `--include-provider-geometry` | Include the provider's raw geometry in the response metadata. | | `--options <json>` | Provider-specific advanced options as a JSON object. | ## `carto lds od-matrix` Compute an origin-destination travel-time and distance matrix. TravelTime provider only. Supply origins and destinations either as repeatable point flags or as JSON arrays of `[lon,lat]` pairs. ```bash # Repeatable point flags carto lds od-matrix \ --origin "-3.70,40.41" --origin "-3.69,40.42" \ --destination "-3.68,40.45" # JSON arrays of [lon,lat] pairs carto lds od-matrix \ --origins-json '[[-3.70,40.41],[-3.69,40.42]]' \ --destinations-json '[[-3.68,40.45]]' ``` | Option | Description | | ---------------------------- | ---------------------------------------------------------------------------- | | `--origin <lon,lat>` | An origin point. Repeatable. | | `--destination <lon,lat>` | A destination point. Repeatable. | | `--origins-json <json>` | Origins as a JSON array of `[lon,lat]` pairs. Replaces `--origin`. | | `--destinations-json <json>` | Destinations as a JSON array of `[lon,lat]` pairs. Replaces `--destination`. | | `--mode <mode>` | Travel mode, provider-dependent. | | `--options <json>` | Provider-specific advanced options as a JSON object. | ## `carto lds capabilities` Show the account's LDS provider for each operation and its quota (annual, used, remaining). ```bash carto lds capabilities carto lds capabilities --json ``` # org Organization-wide statistics and quotas. ## `carto org stats` View organization statistics, resources, and quota consumption. ```bash carto org stats carto org stats --json ``` The displayed information depends on your permissions: * Regular users see resource counts and basic stats. * Admin users see full organization statistics including quotas. * If access is denied for some sections, partial data is shown with notes. **Surfaces shown (when available):** * **Users** — total, editors, viewers, superadmins, API access tokens. * **Resources** — maps (yours and total), workflows, connections, applications. * **Usage & Quotas** — usage quota, LDS credits, geocoding/isolines, map loads. * **AI Quotas** — Builder Gen AI threads, AI Agents tokens. For an example of the full output, see [Examples → Organization statistics](/carto-for-agents/cli/examples#organization-statistics). # users Manage users and invitations in your CARTO organization. User management commands require admin or superadmin permissions. Regular users may not have access to view all organization users; invitation commands require permission to invite users to the organization. ## Identifying a user Commands that act on a specific user take `--user-id` for a user ID or `--user-email` for an email address. SSO user IDs often contain an `@`, so say which kind you are passing. ```bash carto users get --user-email jane@carto.com carto users get --user-id "samlp|my-sso|jane@carto.com" ``` Quote values containing `|` so your shell does not read it as a pipe. ## `carto users list` List every user in the organization. The command returns the full roster in one call; filter the output when you need a subset. ```bash carto users list carto users list --json | jq '[.[] | select(.role == "Builder")]' carto users list --json | jq '[.[] | select(.email | contains("john"))]' ``` {% hint style="info" %} `--all`, `--page`, `--page-size`, `--role` and `--search` were removed in v0.12.0. The API never applied them, and `--all` did not finish for organizations of 100 or more users. A plain `carto users list` returns everyone. {% endhint %} ## `carto users get` Get detailed information for a user. See [Identifying a user](#identifying-a-user). ```bash carto users get --user-email jatorre@carto.com carto users get --user-id "google-oauth2|123456789" carto users get --user-id "samlp|my-sso|jane@carto.com" --json ``` **Options:** | Option | Description | | ---------------------- | ---------------------------------- | | `--user-id <id>` | Look the user up by user ID. | | `--user-email <email>` | Look the user up by email address. | Output includes the user profile, roles, organization, identities, and groups. ## `carto users invite <email[,email...]> [email...]` Invite one or more users to the organization. Both comma-separated and multi-argument forms are accepted. ```bash # Single user carto users invite user@example.com --role Builder # Default role is Viewer carto users invite user@example.com # Comma-separated carto users invite user1@example.com,user2@example.com,user3@example.com --role Builder # Multiple arguments carto users invite user1@example.com user2@example.com --role Viewer ``` **Options:** | Option | Description | | --------------------------------- | ---------------------------------- | | `--role <Builder\|Viewer\|Guest>` | Role to assign. Default: `Viewer`. | **Available roles:** * **Builder** — full access to create and edit maps, workflows, and connections. * **Viewer** — read-only access to view maps and data. * **Guest** — limited access, typically for external collaborators. ## `carto users invitations` List pending invitations. ```bash carto users invitations carto users invitations --json ``` ## `carto users resendInvitation <invitation-id>` Resend a pending invitation. ## `carto users cancelInvitation <invitation-id>` Cancel a pending invitation. ## `carto users delete` Remove a user from the organization and transfer everything they own to another user. Requires Admin permissions. Both users must be identified, the one being removed and the one receiving their content. See [Identifying a user](#identifying-a-user). ```bash # Remove a user, hand their content to a colleague carto users delete --user-email jane@carto.com --receiver-email bob@carto.com # An SSO user ID that contains an "@" carto users delete --user-id "samlp|my-sso|jane@carto.com" --receiver-email bob@carto.com # The two can be identified differently carto users delete --user-email jane@carto.com --receiver-id "auth0|68c97d3137451d6dabeb86c4" ``` **Options:** | Option | Description | | -------------------------- | -------------------------------------------------- | | `--user-id <id>` | User to remove, by user ID. | | `--user-email <email>` | User to remove, by email address. | | `--receiver-id <id>` | User who receives their content, by user ID. | | `--receiver-email <email>` | User who receives their content, by email address. | **What transfers.** Maps, workflows, connections, API access tokens, assets, named sources, hosted apps, folders, and shortcuts all move to the receiving user, along with any SPA OAuth applications. **What does not.** The removed user's machine-to-machine OAuth applications are deleted rather than transferred, so any integration authenticating as that user stops working. Their recent activity, job history, group memberships, and per-user quota settings are also discarded. {% hint style="warning" %} Deleting a user cannot be undone. If the user being removed is a Builder or an Admin, the receiving user needs Builder privileges or higher, otherwise the command is rejected. You cannot delete your own account this way. {% endhint %} The content transfer runs asynchronously, so the receiving user's maps and workflows may take a moment to appear after the command returns. # activity Query and export detailed activity logs and usage data from your CARTO organization. Useful for analyzing user activity, tracking adoption metrics, and building custom dashboards without needing a data warehouse. **Requirements:** Enterprise Large plan or above. ## `carto activity query` Run SQL against your activity data using DuckDB. The CLI automatically downloads the data (if needed), caches it in `/tmp`, and runs your query. **Smart caching:** the first query for a given date range downloads data (\~10s); subsequent queries with the same range are near-instant (\~0.02s). ```bash # Simple count carto activity query --start-date 2025-10-01 --end-date 2025-10-07 \ --sql "SELECT COUNT(*) as total_events FROM activity" # Maps created per user with email carto activity query --start-date 2025-10-01 --end-date 2025-10-07 --sql " SELECT CAST(a.ts AS DATE) as date, u.email, COUNT(*) AS created_maps FROM activity a JOIN userList u ON json_extract_string(a.data, '$.userId') = u.user_id WHERE a.type = 'MapCreated' GROUP BY date, u.email ORDER BY created_maps DESC LIMIT 10 " # Force fresh download carto activity query --start-date 2025-10-01 --end-date 2025-10-07 --no-cache \ --sql "SELECT type, COUNT(*) FROM activity GROUP BY type ORDER BY COUNT(*) DESC" # JSON output carto activity query --start-date 2025-10-01 --end-date 2025-10-07 --json \ --sql "SELECT COUNT(*) FROM activity" ``` **Options:** | Option | Description | | --------------------- | -------------------------------------------------- | | `--start-date <date>` | Start date (`YYYY-MM-DD`). | | `--end-date <date>` | End date (`YYYY-MM-DD`). | | `--sql <sql>` | DuckDB SQL to execute against the activity tables. | | `--no-cache` | Force fresh download (ignore the `/tmp` cache). | | `--json` | Machine-readable JSON output. | ### Available tables | Table | Columns | | ----------- | --------------------------------------------------------------------------------------------------------------------------------- | | `activity` | `type` (VARCHAR — event type, e.g., `MapCreated`, `WorkflowRun`), `ts` (TIMESTAMP UTC), `data` (VARCHAR — JSON payload). | | `apiUsage` | `ts` (TIMESTAMP — daily), `user_id` (VARCHAR), `metric` (VARCHAR — API method), `amount` (NUMBER), `quota_usage_weight` (NUMBER). | | `userList` | `user_id`, `email`, `role`, `created_at`, `group_ids`. | | `groupList` | `group_id`, `group_alias` — only present if groups are enabled. | ### DuckDB SQL tips * JSON extraction: `json_extract_string(data, '$.userId')`. * Date casting: `CAST(ts AS DATE)`. * Date arithmetic: `current_date - INTERVAL 7 DAY`. For the full schema, see [Activity Data Reference](/carto-user-manual/settings/activity-data/activity-data-reference). ## `carto activity export` Export raw activity data to files. Useful for loading into your own data warehouse for advanced analytics, or for archiving. ```bash # Export all categories carto activity export --start-date 2025-10-01 --end-date 2025-10-07 # Export as Parquet (smaller files, faster queries) carto activity export --start-date 2025-10-01 --end-date 2025-10-07 --format parquet # Export only the activity category carto activity export --start-date 2025-10-01 --end-date 2025-10-07 --category activity # Custom output directory carto activity export --start-date 2025-10-01 --end-date 2025-10-07 --output-dir ~/exports ``` **Options:** | Option | Description | | --------------------- | -------------------------------------------------------- | | `--start-date <date>` | Start date (`YYYY-MM-DD`). | | `--end-date <date>` | End date (`YYYY-MM-DD`). | | `--category <name>` | Limit to a specific category (e.g., `activity`). | | `--format <format>` | Output format. `parquet` recommended for large exports. | | `--output-dir <path>` | Output directory. Defaults to current working directory. | **Use cases:** * **Quick SQL analysis** — `activity query` with no warehouse needed. * **Track adoption** — user activity, map creation, workflow execution. * **Monitor quotas** — API usage and quota consumption by user/team. * **Export to warehouse** — load Parquet into BigQuery/Snowflake for advanced analytics. * **Audit trails** — complete event history for compliance. # admin Superadmin operations: list resources across all users, batch delete, and transfer resources between users. Requires superadmin permissions. ## `carto admin list <resource-type>` List all resources across the organization (not just yours). ```bash carto admin list maps carto admin list workflows carto admin list connections # With pagination and search carto admin list maps --page-size 50 carto admin list connections --search snowflake # Fetch every page carto admin list maps --all carto admin list workflows --all ``` **Resource types:** `maps`, `workflows`, `connections`. **Options:** | Option | Description | | ----------------- | ------------------------------ | | `--page <n>` | Page number. | | `--page-size <n>` | Items per page. | | `--search <term>` | Search by name or description. | | `--all` | Fetch all pages automatically. | ## `carto admin batch-delete <json-body>` Delete multiple resources in a single call. ```bash carto admin batch-delete '{"resource_ids":["map1","map2","workflow1"]}' ``` ## `carto admin transfer <json-body>` Transfer resources from one user to another. ```bash carto admin transfer '{ "from_user": "user1@example.com", "to_user": "user2@example.com", "resource_ids": ["map1", "workflow1"] }' ``` ## `carto admin settings get | apply | diff` Round-trip org-wide administrative settings (basemaps toggles, palettes, maps, connections, workflows, builder-gen-ai, carto-ai) as a single JSON bundle. The same shape that `apply` accepts is what `get` emits, so the three subcommands compose for moving settings between environments or capturing a snapshot for audit. ```bash # Dump the current org settings to stdout carto admin settings get # Or write them to a file carto admin settings get --out settings.json # Preview what would change without writing carto admin settings diff settings.json cat settings.json | carto admin settings diff - # Apply a bundle (per-section PATCH — only the sections present in the file are touched) carto admin settings apply settings.json carto admin settings apply --file settings.json cat settings.json | carto admin settings apply - ``` **Subcommands:** | Subcommand | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `settings get` | Read the current org settings as a JSON bundle. | | `settings apply` | Apply a bundle. Sections present in the bundle are PATCHed individually; sections absent from the bundle are left untouched. | | `settings diff` | Preview what `apply` would change. Pure read-only — no writes. | **Options:** | Option | Description | | --------------- | --------------------------------------------------------------------------------------- | | `--out <file>` | (`get` only) Write the bundle to a file instead of stdout. | | `--file <path>` | (`apply` only) Read the bundle from a file instead of the positional argument or stdin. | # ai AI-related commands: chat with the AI agents configured on your maps (`aifeature`), and access CARTO's LLM proxy with an OpenAI-compatible API (`aiproxy`). ## `carto aifeature aiagent <map-id>` Chat with the AI agent configured on a specific map. The CLI automatically fetches the agent's configuration and token — you just need your regular CARTO authentication. ```bash # Interactive multi-turn conversation carto aifeature aiagent <map-id> # Example session: # You: What are the traffic patterns in this area? # Assistant: Based on the data, I can see... # You: Show me the collision hotspots # Assistant: Here are the areas with highest collisions... # You: exit # One-shot mode carto aifeature aiagent <map-id> "What are the traffic patterns?" # Continue a previous conversation carto aifeature aiagent <map-id> "Tell me more" --conversation-id abc123 # Read message from a file carto aifeature aiagent <map-id> --file test-query.txt # Pipe via stdin echo "Analyze the collision data" | carto aifeature aiagent <map-id> # JSON output carto aifeature aiagent <map-id> "Summarize the data" --json ``` **Options:** | Option | Description | | ------------------------ | ----------------------------------------------------------- | | `--conversation-id <id>` | Continue a previous conversation by ID. | | `--file <path>` | Read the message from a file. | | `--json` | Machine-readable JSON output (for automation and CI tests). | **How it works:** * Connects to your map's configured AI agent. * The agent has access to map data, workflows, and configured tools. * Streams responses in real time. * Executes backend tools (workflows, SQL) automatically. * Tracks conversation history for multi-turn interactions. **Use cases:** * **Test agent instructions** — validate behavior during development. * **Debug agent tools** — see which workflows/tools the agent invokes. * **Automated testing** — agent quality scripts. * **Agent development** — rapidly iterate on configuration. * **CI/CD integration** — gate deployments on agent validation. ## `carto aiproxy` Access CARTO's LLM infrastructure directly with an OpenAI-compatible API. Use any available model for custom tasks without going through the AI Features layer. The CLI automatically connects to CARTO's LiteLLM service at `https://litellm-{tenant}.api.carto.com` using your CARTO authentication. ### `carto aiproxy info` Get connection information for external tools. ```bash carto aiproxy info ``` Example output: ``` CARTO LiteLLM Proxy Configuration API Mode: OpenAI Compatible API Host: https://litellm-gcp-us-east1.api.carto.com API Base URL: https://litellm-gcp-us-east1.api.carto.com/v1 API Key: eyJhbGciOiJSUzI1NiIs... Endpoints: Chat completions: /v1/chat/completions Completions: /v1/completions Embeddings: /v1/embeddings Models: /v1/models ``` ### `carto aiproxy models` List available models. ```bash carto aiproxy models ``` ### `carto aiproxy chat <message>` Send a chat message to a model. ```bash # Simple chat carto aiproxy chat "What is 2+2?" --model gpt-4 # With a system prompt carto aiproxy chat "Analyze this data pattern" \ --model gemini-2.5-flash \ --system "You are a geospatial data analyst" # Control generation parameters carto aiproxy chat "Write a haiku about maps" \ --model gpt-4 \ --temperature 1.5 \ --max-tokens 100 # Read message from a file carto aiproxy chat --file prompt.txt --model gpt-4 # Pipe via stdin echo "Explain quantum physics simply" | carto aiproxy chat --model gpt-4 # JSON output carto aiproxy chat "Hello" --model gpt-4 --json ``` **Options:** | Option | Description | | ------------------- | ----------------------------------------------------------------------------- | | `--model <name>` | (Required) Model to use. Run `carto aiproxy models` to list available models. | | `--system <text>` | System prompt to set agent behavior. | | `--temperature <n>` | Sampling temperature, 0–2 (default: 1). Higher = more creative. | | `--max-tokens <n>` | Maximum tokens in the response. | | `--top-p <n>` | Top-p sampling, 0–1 (default: 1). | | `--file <path>` | Read the message from a file. | | `--json` | Output the raw JSON response. | **Use cases:** * **Quick LLM access** — use CARTO's LLM infrastructure for any task. * **Prototyping** — test prompts before building AI Features. * **Data analysis** — get AI insights on your geospatial data. * **Custom scripts** — integrate LLM capabilities into automation. * **Model comparison** — test the same prompt against different models. # app Publish a built frontend as a CARTO-hosted app, or prepare a public build of one you host yourself. A hosted app is a static bundle served at `<workspace-url>/app/<slug>/` behind your organization login; it runs as the signed-in viewer and calls the CARTO API directly. [Hosting your application in CARTO](/carto-for-developers/guides/build-a-hosted-application) walks through building one, and the [Hosted Apps reference](/carto-for-developers/reference/hosted-apps) describes the manifest and the runtime contract; this page is the command reference. {% hint style="info" %} **Private Preview:** Hosted Apps is available to selected accounts during its Private Preview. To request access, contact your CARTO representative. {% endhint %} When Hosted Apps is not enabled for your account, `carto app deploy` exits 1 and explains how to request access (`--json` adds `"code": "hosted-apps-feature-disabled"`). The other commands keep working, so apps already deployed can still be shared, rolled back or deleted. On a CARTO deployment that predates Hosted Apps, the commands that manage hosted apps fail the same way. ## The bundle and `carto.json` The directory you deploy or package is a built static bundle: `index.html` at the root, at most 1000 files, 25 MB per file and 50 MB in total. At runtime the app fetches `./carto-info.json` (relative to its own path) to get the viewer's access token and the CARTO API base URL. An optional `carto.json` at the bundle root declares the backend the app needs: the connections it reads from and the named sources (parametrized SQL) it invokes by name. It is read at deploy or package time and never served. Connections may also list `tables` and `statements`; they only scope the public token when packaging, and `carto app deploy` strips them. `carto app schema` prints the full reference for both files; [App manifest](/carto-for-developers/reference/hosted-apps/app-manifest) documents `carto.json` field by field. ## `carto app deploy <directory>` Package and upload a bundle, provision the backend declared in `carto.json`, and serve the new version. ```bash carto app deploy ./dist --name "Store Explorer" carto app deploy ./dist --slug store-explorer --connection warehouse=my_bigquery carto app deploy ./dist --json ``` **Options:** | Option | Description | | -------------------------- | ---------------------------------------------------------------------- | | `--name <name>` | Display name (default: directory basename). | | `--slug <slug>` | URL slug: lowercase, digits, hyphens (default: slugified name). | | `--version <label>` | Version label, unique per deploy (default: UTC timestamp). | | `--description <text>` | Optional description. | | `--connection handle=name` | Map a `carto.json` connection handle to a real connection. Repeatable. | ## `carto app list` List the hosted apps available to you. ```bash carto app list ``` ## `carto app versions <slug>` List an app's deployed versions and which one is active. ```bash carto app versions store-explorer ``` ## `carto app rollback <slug> [version]` Serve an already-deployed version. Only the bundle changes; the provisioned backend is untouched. ```bash carto app rollback store-explorer 2026-09-01T10:00:00Z carto app rollback store-explorer --version 2026-09-01T10:00:00Z ``` ## `carto app share <slug>` Choose who can open the app: only you, everyone in the organization, or specific groups and users (by id). ```bash carto app share store-explorer --org carto app share store-explorer --group <group-id>,<group-id> carto app share store-explorer --user <user-id> carto app share store-explorer --private ``` **Options:** | Option | Description | | --------------- | --------------------------------------------- | | `--private` | Only you can open it. | | `--org` | Everyone in your organization. | | `--group <ids>` | Share with specific groups (comma-separated). | | `--user <ids>` | Share with specific users (comma-separated). | ## `carto app delete <slug>` Delete the app: every deployed version and the named sources it registered. Asks for confirmation unless `--yes` is passed. ```bash carto app delete store-explorer --yes ``` ## `carto app schema [section]` Print the JSON Schema for `carto.json` (the deploy manifest) and `carto-info.json` (the runtime bootstrap), with every field described. Runs offline. ```bash carto app schema carto app schema connection carto app schema carto-info ``` Sections: `manifest` (default), `connection`, `source`, `migration`, `carto-info`. ## `carto app check <directory>` Safety report before a bundle goes public. Runs offline. It derives the grants a public token would need from `carto.json` (tables, exact statements, named sources), blocks DDL, multi-statement SQL and line comments, flags writes wherever they appear in a statement, and scans every non-binary file for `.env` files, known secret shapes (JWTs, private keys, cloud and Git host keys) and a stray `carto-info.json`. Exit code 1 when something blocks. ```bash carto app check ./dist carto app check ./dist --allow-writes --connection warehouse=my_bigquery ``` **Options:** | Option | Description | | -------------------------- | ------------------------------------------------------------------------- | | `--slug <slug>` | Slug used to name registered sources (default: slugified directory name). | | `--name <name>` | Display name the slug is derived from. | | `--connection handle=name` | Map a `carto.json` connection handle to a real connection. Repeatable. | | `--allow-writes` | Accept `INSERT` / `UPDATE` / `DELETE` grants; otherwise they block. | ## `carto app package <directory>` Build a public version of a bundle you host yourself. It runs the check, registers the manifest's named sources, mints one least-privilege API Access Token named `app:<slug>@<timestamp>-<nonce>` locked to the referer in `--url` (path included when the URL has one), verifies the token by replaying the allowed calls and probing a forbidden one, revokes earlier `app:<slug>` tokens so re-runs are idempotent, and writes `<out>/carto-info.json` next to a copy of the bundle. The package is recorded in `.carto/packages.json`. The token is masked on stdout unless `--show-token` is passed; it is always written to `carto-info.json`. Read-only tokens expire in one year, tokens with write grants in 30 days; `--expires` changes either. ```bash carto app package ./dist --url https://apps.example.com/store-explorer carto app package ./dist --url https://apps.example.com/store-explorer --dry-run carto app package ./dist --url https://apps.example.com/store-explorer --allow-writes --expires 2w carto app package ./dist --update-referer https://apps.example.com/v2/store-explorer ``` **Options:** | Option | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `--out <dir>` | Output folder (default: `<directory>-public`). | | `--url <public-url>` | Where the app will be hosted; locks the token to that referer. | | `--slug <slug>` | Slug used to name registered sources and the token (default: slugified name). | | `--name <name>` | Display name (default: directory basename). | | `--connection handle=name` | Map a `carto.json` connection handle to a real connection. Repeatable. | | `--allow-writes` | Grant `INSERT` / `UPDATE` / `DELETE` statements; the token then expires in 30 days unless `--expires` says otherwise. | | `--expires <when>` | Token expiry: an ISO date, `1d` / `2w` / `6m` / `1y`, or `never` (read-only tokens only). Default: `1y`, or `30d` with writes. | | `--dry-run` | Run the check and show the plan; mint and write nothing. | | `--skip-verify` | Skip replaying the grants against the new token. | | `--show-token` | Print the full token instead of masking it. | | `--update-referer <url>` | Rotate the recorded token so it is restricted to this public URL. | `deploy` publishes an internal app (organization login, viewer token). `package` produces a public one (scoped API Access Token, hosted by you). # Examples End-to-end walkthroughs combining several commands. For per-command details see the [command reference](/carto-for-agents/cli/command-reference). ## Authentication workflow ```bash # Interactive browser-based login using OAuth 2.0 + PKCE carto auth login # This will: # 1. Display an authorization URL # 2. Open your browser (you may need to copy/paste the URL) # 3. Wait for you to complete the login process # 4. Capture your access token and user information # 5. Store credentials in ~/.carto_credentials.json # 6. Configure the API URL based on your tenant # Check authentication status carto auth status # Show current user information carto auth whoami # Returns: user_id, name, email, account info, roles # Switch between profiles carto auth use production carto auth use staging ``` ## Managing application credentials ```bash # List all credentials carto credentials list carto credentials list tokens # Create an API Access Token for your application carto credentials create token \ --connection carto_dw \ --source "demo_tables.*" \ --apis sql,maps # Create SPA OAuth Client for web applications carto credentials create spa \ --title "My Dashboard" \ --callback "https://mydash.com/callback" # Create M2M OAuth Client for backend services carto credentials create m2m \ --title "ETL Service" # Get token details carto credentials get token <token-id> # Delete a credential carto credentials delete token <token-id> ``` ## Browsing and managing resources ```bash # List maps with filters (enhanced display shows owner, privacy, views, tags) carto maps list --search sales --page-size 20 # List only your maps carto maps list --mine # Pagination carto maps list --page 1 --page-size 10 carto maps list --page 2 --page-size 10 # Fetch all pages automatically with --all carto maps list --all carto maps list --mine --all carto workflows list --all --search "project" # Get detailed info for a specific map carto maps get 69b0e7cc-026a-4feb-87bb-a82cc6ac5189 # Output shows: # - Map metadata (title, owner, privacy, views, collaborative, agent enabled) # - Datasets and their connections # - Map URL # JSON output for scripting (or AI agents) carto maps list --json | jq '.data[].id' # Delete a map carto maps delete map_abc123 ``` ## Creating a Builder map from JSON `carto maps create` accepts a round-trippable bundle from a positional JSON string, a filesystem path, or stdin. Pre-flight validation runs before any write, so broken bundles reject without creating an orphan map. ```bash # Minimal bundle — title, connection, and one dataset rendered as a tileset layer cat > stores.map.json <<'JSON' { "title": "Retail stores", "connectionId": "12345678-1234-1234-1234-123456789abc", "privacy": "private", "datasets": [ { "id": "stores-ds", "type": "table", "source": "carto-demo-data.demo_tables.retail_stores", "connectionId": "12345678-1234-1234-1234-123456789abc" } ], "keplerMapConfig": { "config": { "visState": { "layers": [ { "id": "stores-layer", "type": "tileset", "config": { "dataId": "stores-ds", "label": "Stores", "color": [255, 100, 50], "visConfig": { "radius": 10 } } } ] }, "mapStyle": { "styleType": "positron" } } } } JSON # Validate locally (no network), then create carto maps validate < stores.map.json carto maps create < stores.map.json # Or chain in one go carto maps create ./stores.map.json --json | jq '.builderUrl' ``` For the full schema and authoring patterns, see [`carto maps schema`](/carto-for-agents/cli/command-reference/maps#carto-maps-schema-section) and the [`carto-create-builder-maps`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-builder-maps) skill. ### Round-trip: edit an existing map ```bash # Get the map as a round-trippable bundle, edit, and update carto maps get abc123 --json > /tmp/map.json jq '.title = "Q3 Dashboard"' /tmp/map.json | carto maps update abc123 # Update + publish in one call so shared/public viewers see the changes carto maps update abc123 < /tmp/map.json --publish ``` ### Screenshot a map {% hint style="info" %} `carto maps screenshot` is **experimental**. Its flags, render engines, and output may change in future releases. {% endhint %} ```bash # Default light engine — layers + basemap, no widgets carto maps screenshot abc123 -o map.png # Recenter and hide chrome carto maps screenshot abc123 --lat 40.42 --lng -3.70 --zoom 12 --hide-overlays # Full CARTO Builder viewer (widgets, legends, popups) — heavier carto maps screenshot abc123 --render-engine full ``` ## Creating a Workflow from a bundle `carto workflows create --file <bundle.json>` takes a Workflows bundle and provisions the nodes, edges, and metadata in a single call. ```bash # Minimal — pipeline that reads a table, filters it, and writes back cat > cycle-pipeline.workflow.json <<'JSON' { "title": "Cycle network — existing routes only", "connectionId": "12345678-1234-1234-1234-123456789abc", "config": { "schemaVersion": "1.0.0", "connectionProvider": "bigquery", "useCache": false, "nodes": [ { "id": "src", "type": "source", "data": { "name": "ReadTable", "inputs": [ { "name": "source", "value": "demo_tables.bristol_cycle_network" } ] }, "position": { "x": 100, "y": 100 } }, { "id": "filter", "type": "generic", "data": { "name": "native.where", "inputs": [ { "name": "expression", "value": "r_status = 'Existing'" } ] }, "position": { "x": 300, "y": 100 } } ], "edges": [ { "id": "e1", "source": "src", "target": "filter", "sourceHandle": "out", "targetHandle": "source" } ] }, "tags": ["analytics", "cycle-data"] } JSON # Validate offline (Zod-only, no warehouse calls), then create carto workflows validate --file cycle-pipeline.workflow.json carto workflows create --file cycle-pipeline.workflow.json # Full warehouse-side check before merging the bundle to a repo carto workflows verify --file cycle-pipeline.workflow.json --connection carto_dw ``` ### Browse the component catalog Workflows are composed from components — `native.where`, `native.customsql`, `native.joinv2`, and many more. Browse the catalog for a connection (so extensions and stored procedures show up too): ```bash # All Joins components for a BigQuery connection carto workflows components list --connection carto_dw --group Joins # Full input/output signatures for the components you'll use carto workflows components get native.customsql,native.joinv2 --connection carto_dw --json ``` ### Run + publish as an MCP tool ```bash # Execute the workflow carto workflows run abc123 # Make it callable from the CARTO MCP Server (agents will see it as a tool) carto workflows mcp publish abc123 ``` ## Copying maps and workflows between organizations A common pattern is promoting maps and workflows between environments — staging to production, customer A to customer B, or one region to another. The CLI handles connection mapping automatically and validates source accessibility before copying. **Prerequisites:** authenticate to both organizations using [named profiles](/carto-for-agents/cli/authentication#multiple-profiles). You'll need the **ID** of the map or workflow to copy. Get it from the CARTO Workspace (three-dot menu on the card, or from the URL), or search by name with `carto maps list --search "<name>"` / `carto workflows list --search "<name>"`. ```bash # Auto-map connections by name (default, recommended) carto maps copy <map-id> --dest-profile <profile-name> carto workflows copy <workflow-id> --dest-profile <profile-name> ``` By default, CARTO will try to map each connection used by the source resource to a connection **with the same name** in the destination organization. If a Snowflake connection is called `production` in both orgs, the copy works without further configuration. When connection names differ, supply an explicit mapping: {% code overflow="wrap" %} ```bash carto maps copy <map-id> --dest-profile <profile-name> \ --connection-mapping "dev-bq=prod-bq,dev-postgres=prod-postgres" ``` {% endcode %} {% code overflow="wrap" %} ```bash carto workflows copy <workflow-id> --dest-profile <profile-name> \ --connection <connection-name> ``` {% endcode %} {% hint style="info" %} The CLI assumes mapped connections **have the same data access permissions**. If they don't, the copied resources will fail to load. {% endhint %} {% hint style="info" %} Copying does not delete the original resource. {% endhint %} ### Smart connection mapping The CLI handles connection mapping with three strategies, in priority order: 1. **Auto-mapping by name (default)** — match connections by name between source and destination. 2. **Manual mapping** — explicit pairs via `--connection-mapping`. 3. **Legacy single connection** — use one connection for all datasets via `--connection`. ```bash # Auto-map (recommended) carto maps copy abc123 --dest-profile production # → Automatically maps: bigquery-dev → bigquery-dev, snowflake → snowflake # Manual mapping for renamed connections carto maps copy map456 \ --source-profile staging \ --dest-profile production \ --connection-mapping "bigquery-dev=bigquery-prod,snowflake-staging=snowflake-prod" # Legacy: single connection for all datasets carto maps copy xyz789 --dest-profile prod --connection prod-bigquery # Combine options carto maps copy map456 \ --dest-profile production \ --connection-mapping "dev-bq=prod-bq" \ --title "Production Sales Dashboard" \ --keep-privacy ``` **How copy works:** 1. Fetches the source map configuration and all datasets. 2. Identifies all unique connections used by the map. 3. Resolves each connection in priority order: manual mapping → auto-map by name → legacy single connection. 4. Validates that all destination connections exist (fails fast if any are missing). 5. **Validates that dataset sources are accessible** in the destination using SQL dry-run queries (`WHERE 1=0`). Tests permissions and existence without transferring data. Fails if any source is inaccessible (unless `--skip-source-validation`). 6. Creates the new map and datasets with resolved connections. 7. Updates the map configuration with the new dataset IDs. 8. Preserves privacy settings if `--keep-privacy` is set. **Connection resolution scenarios:** *Scenario 1 — Perfect match (auto-mapping):* ```bash carto maps copy abc123 --dest-profile prod # Source has: bigquery-dev, snowflake-analytics # Destination has: bigquery-dev, snowflake-analytics # ✅ Success — both auto-mapped by name ``` *Scenario 2 — Renamed connections (manual mapping):* ```bash carto maps copy abc123 --dest-profile prod \ --connection-mapping "bigquery-dev=bigquery-prod,snowflake-analytics=snowflake-prod" # ✅ Success — both manually mapped ``` *Scenario 3 — Mixed (manual + auto):* ```bash carto maps copy abc123 --dest-profile prod --connection-mapping "old-conn=new-conn" # Source has: old-conn, shared-connection # Destination has: new-conn, shared-connection # ✅ Success — old-conn mapped manually, shared-connection auto-mapped ``` *Scenario 4 — Missing connection:* ```bash carto maps copy abc123 --dest-profile prod # Source has: bigquery-dev, snowflake-analytics # Destination has: bigquery-dev only # ❌ Fails with clear error: # Missing connections in destination organization: # • "snowflake-analytics" (used by 3 datasets) # Solutions: # 1. Create missing connections in destination # 2. Use --connection-mapping to map to different names ``` *Scenario 5 — Source validation failure:* ```bash carto maps copy abc123 --dest-profile prod --connection-mapping "dev-bq=prod-bq" # Connections mapped successfully, but... # ❌ Source validation failed - datasets cannot access their data sources: # • "NYC Traffic" → my-project.dataset.traffic_table # Error: Permission bigquery.tables.get denied on table (or it may not exist) # Solutions: # 1. Grant access to these tables in the destination connection # 2. Ensure tables/views exist in the destination data warehouse # 3. Use --skip-source-validation to create the map anyway ``` *Scenario 6 — Skip source validation (intentional broken map):* ```bash carto maps copy abc123 --dest-profile prod \ --connection-mapping "dev-bq=prod-bq" \ --skip-source-validation # ✅ Success — map created but datasets won't load data until access is fixed ``` ### Troubleshooting **Error: "Connection 'X' not found in destination organization"** * Run `carto connections list --profile <dest-profile>` to see available connections. * Create the missing connection in the destination organization. * Use `--connection-mapping` to map to a different name. **Error: "Source validation failed - datasets cannot access their data sources"** * The destination connection lacks permission to access the source tables/queries. * Grant the necessary permissions in your data warehouse (BigQuery, Snowflake, …). * Verify table names/paths are correct and exist in the destination. * Use `--skip-source-validation` if you want to create the map anyway and fix access later. **Map created but visualizations don't load** * This shouldn't happen with validation enabled (the default). * If you used `--skip-source-validation`, check dataset connections and permissions. ## Organization statistics ```bash # View organization statistics and quotas carto org stats # Example output: # === Organization Statistics === # # Users # Total users: 184 # Editor users: 179 # Viewer users: 1 # Superadmin users: 2 # API Access Tokens: 2,374 # # Resources # Maps: 3,792 (2,897 public) # All users maps: 13,624 # Workflows: 872 # Connections: 569 # Applications: 201 # # Usage & Quotas # Usage quota: 7,702,490 # LDS credits: 1,069,663 of 15,000,000 (7%) # Map loads: 53,194 # # AI Quotas # Builder Gen AI: 0 of 250 threads # AI Agents tokens: 292,187 available # JSON output for scripting carto org stats --json ``` The displayed information depends on your permissions: * **Regular users** — see resource counts and basic stats. * **Admin users** — see full organization statistics including quotas. * **Access denied** for some stats — partial data is shown with notes. ## User management ```bash # List all users carto users list # Filter by role carto users list --role Builder carto users list --role Viewer --all # Search for specific users carto users list --search "john" carto users list --search "@company.com" # Get detailed info, by email or by user ID carto users get --user-email jatorre@carto.com carto users get --user-id "google-oauth2|123456789" # SSO user IDs often contain an "@" — say which kind you are passing carto users get --user-id "samlp|my-sso|jane@company.com" # Remove a user and hand their maps, workflows and connections to a colleague carto users delete --user-email jane@company.com --receiver-email bob@company.com # Invite a single user carto users invite newuser@company.com --role Builder # Invite multiple users at once carto users invite user1@company.com,user2@company.com --role Viewer # Check pending invitations carto users invitations # JSON output for automation carto users list --json | jq '.[] | {email, roles: .app_metadata.roles}' ``` ## Activity data analysis Query activity data with DuckDB SQL — no data warehouse needed. The first query with a given date range downloads data (\~10s); subsequent queries are instant from the local cache. ```bash # Simple count carto activity query --start-date 2025-10-01 --end-date 2025-10-07 \ --sql "SELECT COUNT(*) as total_events FROM activity" # Maps created per user, joined with userList for emails carto activity query --start-date 2025-10-01 --end-date 2025-10-07 --sql " SELECT CAST(a.ts AS DATE) as date, u.email, COUNT(*) AS created_maps FROM activity a JOIN userList u ON json_extract_string(a.data, '$.userId') = u.user_id WHERE a.type = 'MapCreated' GROUP BY date, u.email ORDER BY created_maps DESC LIMIT 10 " # User activity by role carto activity query --start-date 2025-10-01 --end-date 2025-10-07 --sql " SELECT u.email, u.role, COUNT(*) as events FROM activity a JOIN userList u ON json_extract_string(a.data, '$.userId') = u.user_id GROUP BY u.email, u.role ORDER BY events DESC " # Export raw files for loading into your warehouse carto activity export --start-date 2025-10-01 --end-date 2025-10-07 --format parquet ``` See [`activity` command reference](/carto-for-agents/cli/command-reference/activity) for the full schema and DuckDB syntax tips. ## Chatting with a map's AI agent ```bash # Interactive multi-turn conversation carto aifeature aiagent <map-id> # One-shot carto aifeature aiagent <map-id> "What are the traffic patterns?" # Continue a previous conversation carto aifeature aiagent <map-id> "Tell me more" --conversation-id abc123 # Pipe a message echo "Analyze the collision data" | carto aifeature aiagent <map-id> # JSON for automation / CI agent quality tests carto aifeature aiagent <map-id> "Summarize the data" --json ``` Useful for testing agent instructions during development, debugging which workflows the agent invokes, and integrating agent validation into CI pipelines. # Release notes This page tracks user-visible changes to the [CARTO CLI](/carto-for-agents/cli). For the full engineering changelog, see the source repository. {% updates %} {% update date="2026-10-01" %} ## v0.13.0 This release brings the new [Builder map layout](/carto-user-manual/maps/map-layout) to the CLI. You can now create and update maps with a floating or two-column widgets panel, full-width widgets and a set order for the parameters bar, and `carto maps validate` checks a map the same way Builder and the CARTO MCP server do. **Requirements** Changed * The CLI now needs **Node.js 22 or later**. Check with `node --version` and upgrade Node before you run `npm i -g @carto/carto-cli`. **Maps** New * [`carto maps schema widgetspanellayout`](/carto-for-agents/cli/command-reference/maps) documents the widgets panel layout, set in `keplerMapConfig.config.widgetsPanelLayout`. Use `columns` (`1`, or `2` for widgets side by side) and `placement` (`docked` next to the map, or `floating` as a card over it). Without it, a map uses one docked column. With two columns, a widget with `fullWidth: true` takes a whole row. * [`carto maps schema sqlparameters`](/carto-for-agents/cli/command-reference/maps) explains that the order of `sqlParameters` is the order of the parameters bar, from left to right. Changed * `carto maps validate` and `carto maps schema` follow the same map rules as Builder and the CARTO MCP server, so a map that passes validation opens in Builder. When something is wrong, the message names the field and says how to fix it. * `carto maps validate` rejects settings Builder would otherwise ignore or replace without telling you. For example, a widgets panel layout with `columns` other than `1` or `2`, a layer that points to a dataset missing from the map, or an AI Agent with more than four conversation starters. Maps saved from Builder pass as they are. {% endupdate %} {% update date="2026-09-23" %} ## v0.12.0 The headline of this release is **connection sharing from the terminal**: share a connection with your organization, with specific people or with groups, and take that access back again, without opening the Workspace. **Connections** New * New [`carto connections share`](/carto-for-agents/cli/command-reference/connections) and [`carto connections unshare`](/carto-for-agents/cli/command-reference/connections): share a connection with the whole organization (`--org`), with specific users by email (`--with`) or with groups by name or id (`--group`), list who has access (`--list`), and remove access again. New grants are added to what the connection already has. Sharing with users or groups needs a CARTO platform that supports connection access policies; on an older Self-hosted deployment the command stops with an upgrade message before changing anything. [Sharing a connection](/carto-user-manual/connections/sharing-a-connection) in the user manual explains how a shared connection behaves for the people who receive it. * [`carto connections get`](/carto-for-agents/cli/command-reference/connections) shows who the connection is shared with. **Imports** New * [`carto import`](/carto-for-agents/cli/command-reference/imports) tells you when an import finished but lost rows. The job ends as `completed_with_warnings`, which the CLI treats as a success (the table exists), and it prints how many rows were dropped and why: rows without a readable location are in the table without geometry, rows with formatting errors were not imported. `--json` carries `metadata.droppedRows`, `droppedRowReasons` and `droppedRowsByReason`. Fixed * `carto import` streams the file to the upload URL instead of reading it into memory first, so files between 2 GiB and the 5 GB limit now import. They previously failed with `File size (...) is greater than 2 GiB`. **Credentials** Fixed * `carto credentials update token --add-grant '<connection>,<SQL>'` keeps the whole SQL source: only the first comma separates the connection from the source. A malformed value now fails instead of silently storing a partial grant, and the source is required (pass `*` to grant every source). * `carto credentials update token --connection <name> --source <source>` adds a grant, as `create token` does. Both flags were previously accepted and ignored. * `carto credentials --help` documents the `update` flags (`--add-grant`, `--connection` with `--source`, `--add-api`, `--referers`, `--json-body`). **Authentication** Fixed * `carto auth whoami` on an M2M profile reports the service identity (client id, account, acting user, API base URL, token expiry) instead of failing with `404 User not found`. * After `carto auth login` with an account that belongs to no CARTO organization, commands now explain that an organization has to be created in the web app first, instead of asking to log in again. **AI** Fixed * `carto aiproxy chat` and `carto ai` no longer answer "Authentication required" when your organization is not allowed to use the requested model. The proxy's own message is printed, including the models you can use; the login hint is kept for a session that is really invalid. Other proxy errors show their message plus `(HTTP n)`. **Output** Changed * Backend failures are shown from the platform's error contract (title, error, detail), never from the raw response body, so a server stack trace can no longer appear in CLI output. `--json` error codes and per-field details are unchanged. **Configuration** Fixed * The CLI honours `NO_PROXY` / `no_proxy` alongside `HTTPS_PROXY` / `HTTP_PROXY`, as curl and git do. Hosts it matches (exact host, `.domain` suffix, `*.domain`, `host:port`, `*`) are reached directly. Previously every request went through the proxy, so against a Self-Hosted instance on an internal-only hostname `carto auth login` worked but every tenant command failed with the proxy's own DNS error page. `carto activity` downloads now also use the configured proxy. See [Proxies](/carto-for-agents/cli/configuration#proxies). **Users** Breaking changes * [`carto users list`](/carto-for-agents/cli/command-reference/users) drops `--all`, `--page`, `--page-size`, `--role` and `--search`. The API never implemented them: every call returned the organization's full roster, and `--all` never finished for organizations of 100 or more users. A plain `carto users list` returns everyone; filter the output instead, for example `carto users list --json | jq '[.[] | select(.email | contains("ana"))]'`. **Hosted apps** New * The [`carto app`](/carto-for-agents/cli/command-reference/app) command group now appears in `carto --help` and in the command catalogue. It requires the Hosted Apps feature on your account; when the feature is not available, or the CARTO deployment predates it, the commands say so and explain how to request access instead of failing with a 404 (`--json` adds `"code": "hosted-apps-feature-disabled"`). * [`carto app schema [section]`](/carto-for-agents/cli/command-reference/app) prints the JSON Schema for `carto.json` (the deploy manifest) and `carto-info.json` (the runtime bootstrap), with every field described. Runs offline. * [`carto app check <dir>`](/carto-for-agents/cli/command-reference/app) is an offline safety report before a bundle goes public: the grants a public token would need, blocked SQL (DDL, multi-statement, line comments, writes unless `--allow-writes`), and a secret scan of the bundle. Exit 1 when blocked. * [`carto app package <dir>`](/carto-for-agents/cli/command-reference/app) builds a public version of a bundle you host yourself: registers the manifest's named sources, mints one least-privilege API Access Token locked to `--url` (one year for read-only grants, 30 days with writes, `--expires` to change), verifies it, revokes the earlier tokens for the slug, and writes `carto-info.json` next to a copy of the bundle. `--dry-run`, `--skip-verify`, `--show-token`, `--update-referer`. * `carto.json` connections accept `tables` and `statements`, used only to scope the public token when packaging; `carto app deploy` ignores them. **Agents** New * Entries in `carto --commands --json` can carry a `docs` deep link to their reference page, so an agent can point a user at the documentation for the command it just ran. * [`carto maps schema`](/carto-for-agents/cli/command-reference/maps) and [`carto workflows schema`](/carto-for-agents/cli/command-reference/workflows) serve the same section catalogue the MCP server now exposes to agents. Output is unchanged except that ten sections gain a root description, and strings that told the reader to run a CLI command now name the capability instead. {% endupdate %} {% update date="2026-09-01" %} ## v0.11.0 The headline of this release is **stroke styles and polygon fill patterns**, now available when you author maps from the terminal. A map written with the CLI can carry the same styling a Builder user sets by hand. **Maps** New * Layer `visConfig` accepts **stroke styles** on line geometries and polygon borders: `lineStyle` (`solid`, `dashed`, `dotted`), `dashArray` as a `[dash, gap]` pair relative to the stroke width, and `lineStyleRange` to drive the style from a column when `lineStyleField` is set. * Layer `visConfig` accepts **polygon fill patterns**: `fillPatternEnabled` switches a polygon from solid fill to pattern, `fillPattern` selects one of `hlines`, `vlines`, `diag-left`, `diag-right`, `cross-hatch`, `dots`, `checker`, `fillPatternDensity` takes `small`, `medium` or `large`, `fillPatternSize` scales the pattern from `0.1` to `5` (`1` = 100%), and `fillPatternRange` drives the pattern from a column when `fillPatternField` is set. Per-category entries additionally accept `solid` (flat fill color) and `none` (unpainted). * [`carto maps schema`](/carto-for-agents/cli/command-reference/maps) reports the new fields, so agents can discover them without reading these notes. Builder renders stroke styles and fill patterns on **tileset (`mvt`)** layers. `h3` and `quadbin` layers accept the same fields — so a stored map survives a future re-enable — but do not render them yet. For what these look like in Builder, see [Stroke styles](/carto-user-manual/maps/layers#stroke-styles) and [Fill patterns](/carto-user-manual/maps/layers#fill-patterns) in the user manual. **Agents** Breaking changes * Map writes now reject agent configs that exceed the caps Builder's agent dialog enforces, instead of accepting them and producing a map that Builder cannot subsequently edit. [`carto maps create`](/carto-for-agents/cli/command-reference/maps) and [`update`](/carto-for-agents/cli/command-reference/maps) fail when `config.useCase` is over 500 characters, `config.introduction.starters` has more than 4 entries, `config.introduction.welcome` is over 300 characters, or any single starter is over 100 characters. A bundle with more than 4 starters previously saved and then failed the viewer with a 500. Trim these fields to bring an existing bundle back within the caps. {% endupdate %} {% update date="2026-08-31" %} ## v0.10.2 The headline of this release is **Location Data Services from the terminal**: geocoding, reverse geocoding, isolines, routing, and origin-destination matrices, all under the new [`carto lds`](/carto-for-agents/cli/command-reference/lds) command group. **Location Services** New * New [`carto lds`](/carto-for-agents/cli/command-reference/lds) command group brings CARTO Location Data Services to the terminal: [`geocode`](/carto-for-agents/cli/command-reference/lds), [`reverse-geocode`](/carto-for-agents/cli/command-reference/lds), [`isolines`](/carto-for-agents/cli/command-reference/lds), [`routing`](/carto-for-agents/cli/command-reference/lds), [`od-matrix`](/carto-for-agents/cli/command-reference/lds), and [`capabilities`](/carto-for-agents/cli/command-reference/lds) (which reports your provider and remaining quota per operation). Every subcommand supports `--json`. **Transfer** New * [`carto transfer`](/carto-for-agents/cli/command-reference/transfer) gains `--overwrite` to replace an existing destination table (staged, so the current table survives a failed transfer), `--target-srid <epsg>` to reproject geometry at the destination, and `--preserve-source-crs` to keep the source CRS instead of applying the destination's convention. **SQL** Breaking changes * [`carto sql query`](/carto-for-agents/cli/command-reference/sql) no longer accepts `--cache`. The flag issued a cached `GET` that no longer cached anything and capped query length at roughly 8 KB. `sql query` now always `POST`s, with no length limit. Remove `--cache` from any script that passes it. **Workflows** Breaking changes * [`carto workflows share`](/carto-for-agents/cli/command-reference/workflows) and [`unshare`](/carto-for-agents/cli/command-reference/workflows) no longer accept `--user-id` or `--user-email`. Identify users with `--with <email>`, which is repeatable and comma-separated. This withdraws the `--user-id` / `--user-email` flags that `0.9.1` and `0.9.2` introduced. Any user with an email is still reachable; sharing by user ID alone is tracked as a separate request. Fix * [`carto workflows get`](/carto-for-agents/cli/command-reference/workflows), [`create`](/carto-for-agents/cli/command-reference/workflows), and [`update`](/carto-for-agents/cli/command-reference/workflows) now honor `--profile`. The flag was silently ignored on these three subcommands, so cross-org flows went out with the default profile's token and failed with a misleading "Permission denied". * [`carto workflows validate`](/carto-for-agents/cli/command-reference/workflows) now reports an edge whose `targetHandle` names an input the target node does not declare. Such an edge draws no connection line on the canvas even though the engine still runs it, so it previously surfaced only as a broken-looking DAG. **Maps** Fix * [`carto maps create`](/carto-for-agents/cli/command-reference/maps) and [`update`](/carto-for-agents/cli/command-reference/maps) no longer reject accessible Oracle (and other non-BigQuery) sources. The pre-create source probe used BigQuery-only SQL against every warehouse, so valid sources failed as false negatives. The probe now speaks each provider's dialect and surfaces the real warehouse error. New * [`carto maps validate`](/carto-for-agents/cli/command-reference/maps) rejects single-select Category SQL parameters that would load inconsistently in Builder. **Listing** Fix * [`carto workflows list`](/carto-for-agents/cli/command-reference/workflows) and [`carto maps list`](/carto-for-agents/cli/command-reference/maps) with `--order-by updatedAt` (or `createdAt`) no longer return HTTP 500. The camelCase forms the help advertises are now normalized before the request. **Imports** Fix * [`carto imports`](/carto-for-agents/cli/command-reference/imports) accepts files up to 5 GB, matching the server. A stale client-side guard had rejected anything over 1 GB. **Authentication** Fix * `--base-url` no longer requires the default profile's tenant to be reachable, so an override works even when that tenant is not. An empty `--token` now errors clearly instead of silently falling back to the stored profile. **Credentials** Improvement * [`carto credentials create token --apis`](/carto-for-agents/cli/command-reference/credentials) documents the `exports` scope, which [`carto export`](/carto-for-agents/cli/command-reference/export) requires. **Security** Improvement * The CLI writes `~/.carto/config.json` with owner-only (`0600`) permissions, and masks the `aiproxy` API key in command output. {% endupdate %} {% update date="2026-07-30" %} ## v0.9.2 **Users** New * [`carto users get`](/carto-for-agents/cli/command-reference/users) and [`carto users delete`](/carto-for-agents/cli/command-reference/users) now take an explicit `--user-id` or `--user-email` flag to say which user you mean, and `users delete` takes `--receiver-id` or `--receiver-email` for the user who inherits the content. Both commands used to infer the kind from the value and read anything containing an `@` as an email, so a user whose SSO ID contains one (`samlp|my-sso|jane@carto.com`) could not be targeted at all. See [Identifying a user](/carto-for-agents/cli/command-reference/users#identifying-a-user). **Workflows** New * [`carto workflows share`](/carto-for-agents/cli/command-reference/workflows) and [`unshare`](/carto-for-agents/cli/command-reference/workflows) accept `--user-id` alongside `--user-email`, both repeatable and comma-separated. Sharing with a user by ID was not possible before, so SSO users whose ID contains an `@` were out of reach here too. **All commands** Improvement * Flags accept the `--flag=value` form in addition to `--flag value`. This is the only way to pass a value that itself starts with `--`. {% endupdate %} {% update date="2026-06-29" %} ## v0.9.0 **Workflows** Breaking changes * [`carto workflows validate`](/carto-for-agents/cli/command-reference/workflows) now validates against the connection's **live component catalog** instead of running fully offline. On top of the structural checks, it confirms that every component name and parameter exists in the connection's catalog — native functions, extensions, and stored procedures. As a result it needs a connection (read from the bundle's `connectionId`, or supplied with the new `--connection <name|uuid>` flag) and an authenticated session. [`carto workflows create`](/carto-for-agents/cli/command-reference/workflows) and [`update`](/carto-for-agents/cli/command-reference/workflows) run the same catalog-aware pre-flight before submitting. {% hint style="warning" %} **Migration**: `workflows validate` previously made no API calls. If you run it in CI, make sure the bundle carries a `connectionId` (or pass `--connection`) and that the environment is authenticated. {% endhint %} **SQL** New * [`carto sql query`](/carto-for-agents/cli/command-reference/sql) and [`carto sql job`](/carto-for-agents/cli/command-reference/sql) accept `--param key=value` (repeatable) and `--params-json '<json>'` to bind query parameters. `--param` values are JSON-parsed — numbers, booleans, and arrays keep their type, everything else is treated as a string — while `--params-json` takes a full JSON object or array for complete control. The two flags can't be combined. * [`carto sql query`](/carto-for-agents/cli/command-reference/sql) also accepts a [named source](/carto-for-agents/cli/command-reference/named-sources) name in the SQL position, so you can run a saved query by name (and bind its parameters with `--param`) without writing the SQL by hand. **Admin** Fix * [`carto admin settings apply`](/carto-for-agents/cli/command-reference/admin) now reports any models the API failed to apply, so partial failures surface instead of appearing to succeed. {% endupdate %} {% update date="2026-05-29" %} ## v0.8.0 **Workflows** Breaking changes * [`carto workflows verify-remote`](/carto-for-agents/cli/command-reference/workflows) no longer fails on advisory warnings. The exit code (and the `valid` field on `--json` output) now reflects whether the workflow would be accepted by `workflows create`. Warnings are still listed in the output, but on their own they no longer break the run. {% hint style="warning" %} **Migration**: if you have a CI gate that relied on any warning failing the build, pass the new `--strict` flag to restore the previous behaviour. {% endhint %} New * [`carto workflows verify-remote --strict`](/carto-for-agents/cli/command-reference/workflows) restores the previous behaviour, where any warning fails the exit code. Useful for CI gates that want to enforce a clean run. Improvement * [`carto workflows components get --json`](/carto-for-agents/cli/command-reference/workflows) now returns the human-readable option labels alongside the values that components accept. For inputs like `native.isolines.mode`, bundle authors can pick the value the engine expects (`"walk"`) without mistaking it for the display label (`"Walk"`). * [`carto workflows create`](/carto-for-agents/cli/command-reference/workflows) accepts both a stringified `FeatureCollection` and a `FeatureCollection` object on the `native.tablefromgeojson` and `native.drawcustomgeographies` components, so workflows that ingest GeoJSON can now be authored from the CLI. Fix * [`carto workflows create`](/carto-for-agents/cli/command-reference/workflows) now prints the canonical workflow URL on success, so callers no longer have to assemble it themselves. **Maps** Improvement * [`carto maps schema layers`](/carto-for-agents/cli/command-reference/maps) now lists the four `Scale with zoom level` radius fields for tileset point layers — `radiusScaleWithZoom`, `radiusReferenceZoom`, `sizeMinPixels`, `sizeMaxPixels` — so bundle authors can discover the mode. [`carto maps validate`](/carto-for-agents/cli/command-reference/maps) also rejects two shapes that would silently break in Builder: `radiusScaleWithZoom: true` without a `radius` value, and `radiusScaleWithZoom: true` alongside a `radiusField`. Fix * [`carto maps create`](/carto-for-agents/cli/command-reference/maps) now emits the correct Builder URL. The URL could previously fall back to a different host that returned 404. **Connections** Fix * [`carto connections browse --max-items`](/carto-for-agents/cli/command-reference/connections) and `--max-children` are now honoured. Both flags were silently dropped, so browse output capped at 30 items regardless of value. **Credentials** New * [`carto credentials create token`](/carto-for-agents/cli/command-reference/credentials) accepts wildcard `--source` patterns (e.g. `"carto.shared.CARTO_*"`, or `"*"` for all sources on the connection), an `--expiration-date` flag (ISO date or shorthand like `30d` / `6m` / `1y`), and an optional `--name` label, so a single token can be scoped to a fleet of warehouses and aged out automatically. **Admin** New * [`carto admin settings get|apply|diff`](/carto-for-agents/cli/command-reference/admin) round-trips org-wide administrative settings (basemaps toggles, palettes, maps, connections, workflows, builder-gen-ai, carto-ai) as a single JSON bundle. Useful for moving settings between environments or capturing a snapshot for audit. {% endupdate %} {% update date="2026-05-14" %} ## v0.7.1 **Maps** Improvement * The `add_layer` core tool surfaced by [`carto maps agents core-tools`](/carto-for-agents/cli/command-reference/maps) now accepts `clickColumns` and `clickColumnsAggregation`, so the Builder AI agent can author click popups end-to-end (previously only hover popups were configurable). Aggregation rules mirror `hoverColumns` / `hoverColumnsAggregation`, and `clickColumns` has no field-count cap (the hover cap of 5 still applies). {% endupdate %} {% update date="2026-05-13" %} ## v0.7.0 This release introduces **map and workflow authoring from the command line** and lands alongside the new [CARTO for Agents](/carto-for-agents/carto-for-agents) section, which brings the CLI together with the [CARTO MCP Server](/carto-for-agents/mcp-server) and the [Agent Skills](/carto-for-agents/agent-skills) catalog. **Maps** New * Author Builder maps end-to-end from the CLI. [`carto maps create`](/carto-for-agents/cli/command-reference/maps) and [`carto maps update`](/carto-for-agents/cli/command-reference/maps) accept a round-trippable JSON bundle as a positional argument, a filesystem path, or via stdin. The bundle returned by `maps get --json` can be piped straight back into `create` or `update`. * New commands round out the authoring loop: [`maps validate`](/carto-for-agents/cli/command-reference/maps) (offline pre-flight, no API calls), [`maps verify-remote`](/carto-for-agents/cli/command-reference/maps) (pre-flight plus warehouse-side dry-runs), [`maps publish`](/carto-for-agents/cli/command-reference/maps) (freeze a snapshot so shared and public viewers see the current state), [`maps schema`](/carto-for-agents/cli/command-reference/maps) (JSON Schema reference for bundle authors), [`maps agents`](/carto-for-agents/cli/command-reference/maps) (inspect the AI surface available on a tenant), and [`maps copy --dest-profile`](/carto-for-agents/cli/command-reference/maps) (duplicate a map across organizations). * `maps create` and `maps update` responses now expose `builderUrl`, `viewerUrl`, and `publicUrl` as first-class fields. Improvement * Bundles are pre-flight validated before any API call, with clear pointers to the offending field on failure. Broken sources, missing required fields, and shapes that would render incorrectly in Builder are rejected locally. * Sensible defaults are auto-filled when bundle fields are omitted (popup `enabled`, widget `operationColumn`, `collapsible`, basemap and viewport hydration from `/stats`), so smaller bundles "just work". **Workflows** New * Author and validate workflows from the CLI. [`carto workflows create`](/carto-for-agents/cli/command-reference/workflows), [`update`](/carto-for-agents/cli/command-reference/workflows), and [`validate`](/carto-for-agents/cli/command-reference/workflows) (offline schema check), plus the new [`workflows verify`](/carto-for-agents/cli/command-reference/workflows) command — warehouse-aware validation that requires `--connection <name|uuid>` and runs the full structural, engine-compile, schema-trace, and sources stack without writing the workflow. * [`carto workflows components list`](/carto-for-agents/cli/command-reference/workflows) and [`get`](/carto-for-agents/cli/command-reference/workflows) surface the agent-facing component catalog. Both require `--connection <name|uuid>` so extension and stored-procedure components appear alongside native ones. Fix * `carto workflows list --order-by updated|created` no longer fails with a 500. The CLI now aliases `updated` → `updated_at` and `created` → `created_at` before calling the API. Canonical values still work unchanged. {% hint style="info" %} For end-to-end recipes — including the agent skills that drive these flows — see the [`carto-create-builder-maps`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-builder-maps) and [`carto-create-workflow`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-workflow) skills in the [agent-skills repository](https://github.com/CartoDB/agent-skills), and the [CARTO for Agents](/carto-for-agents/carto-for-agents) section. {% endhint %} {% endupdate %} {% update date="2026-04-27" %} ## v0.6.0 Breaking changes * [`carto export`](/carto-for-agents/cli/command-reference/export) no longer accepts `--query`. Use `--select <cols>` (comma-separated column list) and `--where <predicate>` (warehouse-native SQL, no leading `WHERE`) instead. `--limit` is unchanged. {% hint style="warning" %} **Migration**: rewrite `carto export --query "SELECT a, b FROM t WHERE c > 0"` as `carto export <t> --select a,b --where "c > 0"`. {% endhint %} {% endupdate %} {% update date="2026-04-25" %} ## v0.5.0 Fix * Kebab-case flag forms (`--page-size`, `--order-by`, `--order-direction`, `--max-children`) on list commands now work as documented across `maps`, `workflows`, `connections`, `users`, `credentials`, and `admin`. The camelCase forms (`--pageSize`, `--orderBy`, …) continue to work as aliases. {% endupdate %} {% update date="2025-12-31" %} ## v0.1.0 New * Initial release of the CARTO CLI. * Multi-profile authentication, including M2M OAuth for CI/CD pipelines. * Commands for `maps`, `workflows`, `connections`, `credentials`, `users`, `imports`, and `admin`, with JSON output mode for scripting. {% endupdate %} {% endupdates %} # Overview The CARTO Workspace is the user interface for our next generation cloud-native Location Intelligence platform. It allows you to create stunning maps and perform spatial analytics at scale, with everything running directly on top of your cloud data warehouse(s). Learn how to make the most out of our Builder tool, Analytics Toolbox, Data Observatory, and other new features. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-186e451eaa60c7924ab04a921acd4bd223b19306%2FScreenshot%202023-01-12%20at%2018.25.14.png?alt=media" alt="Screenshot of the CARTO Workspace showing onboarding materials"><figcaption></figcaption></figure> Check out the following pages for setting up your organization, getting acclimated to the workspace, and creating your first map: * [CARTO Workspace overview](/carto-user-manual/overview/carto-workspace-overview) * [Creating your first map](/getting-started/quickstart-guides/creating-your-first-map) # Creating your CARTO organization In this guide, we'll walk through the process of creating your first CARTO organization. This will be the first step to start creating stunning maps and perform spatial analytics at scale, with everything running directly on top of your cloud data warehouse. 1. **Account sign up** * Go to the [CARTO Sign up](http://app.carto.com/signup) page. * Enter your email address and password. You can also sign up with your existing Google account by clicking *Continue with Google*. * Follow the steps to verify your email and continue with your new organization setup. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-dd623bd35ad32f25959b15d7908689b7f29b6b6b%2FScreenshot%202024-04-02%20at%2017.57.18.png?alt=media" alt=""><figcaption></figcaption></figure> 2. **Organization setup** If your email domain is already associated with an existing CARTO organization, you will be able to join (or request to join) any of the existing organizations associated with that domain. Alternatively, you will be able to create a brand new organization. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-afd03de680c6593dfe879a57ff9806bef4e7cd29%2FScreenshot%202024-04-02%20at%2018.25.19.png?alt=media" alt=""><figcaption></figcaption></figure> For new organizations, you will need to choose an organization name (e.g. CARTO) and a **deployment region**. As a rule of thumb, you should choose the region closest to your data warehouse. For more information, check our article on [deployment regions](/carto-user-manual/overview/carto-cloud-regions). After finishing the form, click "Let's get started with CARTO!" to complete the sign up process and get access to the CARTO Workspace. By signing up you accept the [Terms and conditions of the Services](https://carto.com/legal/) and the [privacy notice](https://carto.com/privacy/). You are ready to start using CARTO! # CARTO Cloud Regions For new CARTO [**cloud deployments**](/faqs/deployment-options), users can choose between four different regions. These correspond to four separate CARTO tenants, each located in a different geographical location: * United States East * Europe West (located in the EU) * Asia Northeast (located in Japan) * Australia Southeast <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-17f8fa00090186b03895b6c548b51efdb723a898%2FScreenshot%202024-04-12%20at%2012.45.12.png?alt=media" alt=""><figcaption></figcaption></figure> These tenants are fully managed CARTO deployments that we host on our own cloud (on the Google Cloud Platform). We manage configuration, updates, and versioning. Changes to CARTO are pushed simultaneously to these four tenants, so they are functionally equivalent. All your organization’s data such as maps, workflows, applications, etc; will be stored in the selected region. In addition, the [CARTO Data Warehouse](/carto-user-manual/connections/carto-data-warehouse) of your organization will be located in that region as well. ### Choosing a region There are a two main considerations when choosing a region: * Proximity to your data * Compliance and data regulations Ideally, you should choose the region that is closest to your data to reduce latency and improve performance. For example, if you’re planning to connect CARTO to your Google BigQuery or Snowflake data in any US region, we recommend you choose the CARTO US region for optimal performance. Some organizations might also have to choose a region that complies with specific data protection and privacy regulations, such as GDPR in the EU. For additional help, you can use [**Google Cloud's Region Picker**](https://googlecloudplatform.github.io/region-picker/) to help you select a cloud region. ### Checking my organization's region The region of your organization is visible from the admin panel in the [Organization Settings](/carto-user-manual/settings). <figure><img src="https://lh7-us.googleusercontent.com/2V5JeQ-3svQAJmb1d-hsLuu8tAJL4m1c36rJ5WygAi6PBSsbQ5qn4ZP9yTUOI6PnVjNSXL6WY6Zfa7CTfovApOgkwpny9QWoUzFAu1suTQdwf1JOBqI0OBL59FAPdluAJPhH8klnbFosO4TW8vpCEFU" alt=""><figcaption></figcaption></figure> If you're not an admin, you can still check your organization's region by looking at the URL: * *clausa* stands for United States East * *pinea* for Europe West * *thunbergii* for Asia Northeast * *radiata* for Australia Southeast\ \ \\ # CARTO Workspace overview Learn everything you need to know about your Workspace and how to make the most out of it. When you log in to your CARTO user account, you will be presented with your Workspace. The Workspace allows you to access all components of the CARTO platform via a single interface. It will allow you to manage connections to your data warehouse(s), explore your data, subscribe to Data Observatory datasets, develop spatial applications, and run visualizations and spatial analysis through our tools Builder and Workflows. ## **Homepage** The first time that you access the Workspace, you will see a *Welcome* banner with links providing quick access to different actions to get you started with CARTO, like creating your first connection or your first map and workflow, or starting with your spatial analysis in an easy guided way from our editable pre-built demo maps and demo workflows. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-5bdcf8f0edfff2af8f678a95697e0a90731a4199%2FScreenshot%202024-07-05%20at%2012.58.20.png?alt=media" alt=""><figcaption></figcaption></figure> From the **“Connect your data warehouse”** banner, you can easily connect your data warehouse(s) to start using CARTO by clicking on *Create new connection* button. Check the quick guides to [connect data](/getting-started/quickstart-guides/connecting-to-your-data) and [creating your first map](/getting-started/quickstart-guides/creating-your-first-map) to get started. After creating your connection, you can also **upload local files** right from the homepage by clicking on *Import your data* button. Check this [guide](/carto-user-manual/data-explorer/importing-data) to start importing your data into your data warehouse. From the **“What's new”** section, you will find announcements of new features, interesting articles, and the latest news related to CARTO from our blog. Stay tuned and don’t miss out on the latest news! <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-7b8336c0d878403ed607ce96dc2152123333a915%2FScreenshot%202024-07-05%20at%2012.59.34.png?alt=media" alt=""><figcaption></figcaption></figure> ## **Getting started** In this section you have a checklist with five quick steps to guide you to the different content pieces to help you get started with CARTO. Once you have completed all the steps, it will be marked as completed and you can close the panel by clicking on *Close*. If you want to skip the steps, just click on *I´m ready, skip onboarding* to close the panel. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-4a8a97ba18e5a07f0e18161a0067aa953a5f8c17%2FCaptura%20de%20pantalla%202023-09-08%20a%20las%2012.14.24.png?alt=media" alt="" width="375"><figcaption></figcaption></figure> ## **Help sidebar** The help sidebar is always available, including when you're creating Maps and Workflows. It contains: * An **AI-powered search bar**, similar to the one you can use in this documentation. Ask anything about CARTO and get quick answers, pointing in the right direction and including a link to this documentation. * Relevant links to our [What's new](/whats-new) section, the [CARTO Academy](https://academy.carto.com), and the [CARTO Support ](/faqs/support-packages)team. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-d1bfabd8d46346a979e8d94981e541ed40abc494%2FScreenshot%202024-04-11%20at%2013.39.48.png?alt=media" alt=""><figcaption></figcaption></figure> ## **Recent projects** View your latest [projects](/carto-user-manual/projects). This module displays the projects you have worked on most recently, so you can jump straight back into them, and shows how many items each one holds. Click *View all* to open the full Projects section. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-2dbe3f8e0ff94cf361968fb795413546fae08de3%2Frecent-projects.png?alt=media" alt=""><figcaption></figcaption></figure> ## **Recent maps** View your latest content. This module displays the latest maps that you have been working on, so that you can quickly access and continue working on them. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-ca584298cef102eee1b50e98d678e468d56c226f%2Frecent_maps.png?alt=media&token=b17b0494-fde2-4865-839b-a3e25c79d474" alt=""><figcaption></figcaption></figure> If you are the owner of the map, you will have access to the quick actions menu to manage your map by clicking on the three dot icon of the map card. There are 4 options available: Edit map properties, [Share](/carto-user-manual/maps/sharing-and-collaboration), [Duplicating maps](/carto-user-manual/maps/managing-maps#duplicating-maps) and [Delete](/carto-user-manual/maps/managing-maps#deleting-maps). <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-016c8cc1fef346ce7a36944eb7f397bfb3bb92a7%2Fimage.png?alt=media" alt="" width="337"><figcaption></figcaption></figure> ## **Recent workflows** View your latest accessed workflows. This module displays the latest workflows that you have been working on, so that you can quickly access and continue working on them. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-c2a235229e65d3fbe33eb158408be26577615fdf%2FCaptura%20de%20pantalla%202023-09-08%20a%20las%2012.22.47.png?alt=media" alt=""><figcaption></figcaption></figure> ## **Recent datasets** View your latest datasets for easy access. This module displays the latest datasets that you have been working on, so that you can quickly access and continue working on them. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-2613a242e56c54f7c96b906310127236b0cac5ac%2Frecent_datasets_new.png?alt=media&token=7e68a75f-83a1-4953-a9c2-769e74cd3ba1" alt=""><figcaption></figcaption></figure> ## **Navigation Menu** In the left panel, you can find the *Navigation Menu* with all the available options to access the CARTO components: Home, Maps, Data Explorer, Data Observatory, Connections, Settings, and Developers. In the bottom part of the menu, you have additional options to join the “CARTO Users” Slack channel, send us direct product feedback, or access the Documentation portal. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-7bd9d99b82cd59e4b907ea2c34f79c6ea2f1ac18%2Fthe_menu_sections.png?alt=media&token=1ed47894-d9ea-4798-ab7c-8dc651b9fa7b" alt=""><figcaption></figcaption></figure> # Projects Organize your maps and workflows into projects and folders, and manage sharing for everything inside from a single place. Projects and folders let you organize your maps and workflows into a clear structure instead of a single flat list. A **project** is a top-level container, and a **folder** lives inside a project or another folder. With them you can: * **Move maps and workflows into them** to keep related work together. * **Manage sharing from the top.** Share a project or folder once and everything inside it inherits that access, so you set permissions in one place instead of item by item. * **Add shortcuts** for maps or workflows that need to live in more than one place, or for assets you do not own. Organize your work however suits you, and nest folders as deep as you need. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-b46ea9e42edd84dcc1475750c14255a8244fec23%2Fprojects-list.png?alt=media" alt=""><figcaption>The Projects section, with a New project button and one card per project</figcaption></figure> ## Creating projects and folders Projects live in the **Projects** section of the Workspace. Click **New project** and give it a name. Open the project and use the new-folder button to add folders inside it, nesting them as deep as you need. To start something new right where it belongs, use **New asset** to create a map, workflow, or AI Agent (or a workflow from a template) directly inside a project or folder. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-cd71a01755dc7c599ebf7652ac7be6deff2ba9b0%2Fproject-new-folder.png?alt=media" alt=""><figcaption>Creating a folder inside a project</figcaption></figure> ## Organizing your maps and workflows To bring existing work into a project or folder, move it in. In the Maps or Workflows section, open the three-dot menu on the card and select **Move to**. Pick a destination by switching between your own and others' projects, following the breadcrumb, and drilling into folders; you can also create a new project or folder without leaving the modal. Confirm with **Move here**. The map or workflow now lives in that project or folder and takes on its sharing (see [Sharing projects and folders](#sharing-projects-and-folders)). It lives in one project or folder at a time, and only maps, workflows, folders, and shortcuts can live inside one, so connections, datasets, and other resources stay in their own sections. The same **Move to** flow relocates a map or workflow between projects and folders, and **Remove from project** (or **Remove from folder**) takes it back out. Moving or removing only changes where a map or workflow lives and the sharing it inherits; it never deletes the map or workflow itself. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-16f7fe4b7fe5affdb7398fe117a3d55cc43dce38%2Fmove-map-to-project.png?alt=media" alt=""><figcaption>The Move to modal, where you pick the destination project or folder</figcaption></figure> {% hint style="info" %} Wherever a map or workflow lives, it is always accessible from the **Maps** and **Workflows** sections of your Workspace. Projects and folders organize your content, they do not hide it from those lists. {% endhint %} ### Shortcuts Moving is the usual way to place a map or workflow. When the same one needs to appear in more than one place, or you want to reference an asset you do not own, add a **shortcut** instead. Open the three-dot menu on the card and select **Create shortcut**. A shortcut is just a pointer: it does not move the original or make a copy. Shortcuts inherit nothing. The map or workflow a shortcut points to keeps its own sharing, and a shortcut placed inside a shared project does not grant anyone access to it. Deleting a shortcut removes only the pointer, never the original. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-7f2f40cfabdae3c0b5dc34c283c11c50e61fa31f%2Fproject-contents.png?alt=media" alt=""><figcaption>A project holding a folder and a map</figcaption></figure> ## Sharing projects and folders You share a project or folder the same way you share a single map or workflow: pick a mode (Restricted or Organization) and add the users or groups who should have access. Only the owner can change how a project or folder is shared. See [Sharing and collaboration](/carto-user-manual/maps/sharing-and-collaboration) for maps and [Sharing workflows](/carto-user-manual/workflows/sharing-workflows) for workflows. When you share a project or folder, everything inside inherits that access, so you set permissions once instead of item by item. Sharing a project covers its folders, maps, and workflows; sharing a folder covers everything in that folder. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-436bc395a3601b1fe46c6e1021c154764d89657d%2Fproject-share.png?alt=media" alt=""><figcaption>Sharing a project. Lower-level folders and content inherit these settings</figcaption></figure> Inheritance is **additive**: a map or workflow keeps its own sharing and gains whatever it inherits from the project or folder above it. A map shared with person X that you move into a folder shared with team Y ends up accessible to both X and Y. In the map or workflow's own Share modal, inherited access is labeled **Access is inherited from an upper level**, so you can tell it apart from access set directly on the asset, and you can still add more people or groups on top. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-372959788cf58a2376e8302993c8084991cfd19f%2Fshare-access-inherited.png?alt=media" alt=""><figcaption>On a map, access inherited from a parent project or folder is labeled in the Share modal</figcaption></figure> {% hint style="warning" %} **Shortcuts do not inherit sharing.** A shortcut inside a shared project stays a pointer. The map or workflow it points to keeps its own sharing settings, so someone who can open the project will only be able to open the target through the shortcut if that map or workflow has been shared with them directly. {% endhint %} {% hint style="info" %} Projects and folders can only be Restricted or Organization; they cannot be made public. A map inside a project can still be shared publicly on its own, unless an admin has disabled public map sharing from the [Governance](/carto-user-manual/settings/organization-governance) settings. {% endhint %} ## Managing projects and folders From the three-dot menu on a project or folder card, or the header when you are inside it, you can rename it, share it, move a folder into another project or folder, and delete it. Like the Maps and Workflows sections, the Projects section can be shown as a grid or a list, and you can search, sort, and filter by owner. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-bd85feae2da6826fca1b9efd5fc12077730cf653%2Fproject-card-menu.png?alt=media" alt=""><figcaption>The project card menu: rename, share, or delete</figcaption></figure> {% hint style="info" %} **Deleting a project or folder never deletes the maps and workflows inside it.** They stay available from the Maps and Workflows sections and only lose the sharing they inherited from that project or folder. To delete a map or workflow, do it explicitly from its own card. {% endhint %} ## Managing projects from the CLI Projects and folders can also be created, browsed, and reorganized programmatically with the CARTO CLI. See the [`projects` command reference](/carto-for-agents/cli/command-reference/projects). # Maps The CARTO Workspace includes functionalities for creating and publishing maps in a simple manner, using the CARTO map tool: Builder. Builder is designed to allow technical and non-technical audiences to visualize, explore, and filter large amount of location data in your browser. This guide will teach you how to create a map in the CARTO Builder, and perform data analysis by adding data to a map, adding filters, and more. In the Maps section of the Workspace, you will see the list of your current maps. If you haven’t created a map yet, you will see the following page: <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-056dd14c18a2cf2291f0a04912b307cdf5a3c860%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> To create a new map, click *Create your first map*. This will open the CARTO map tool: Builder. CARTO Builder contains many features that guide you through the process of creating a map, changing the styling, and selecting how your data appears. Use the following task list as guide for some of the main CARTO Builder features: * Add your data [guide](/carto-user-manual/maps/data-sources#adding-a-data-source) * Style your maps [guide](/carto-user-manual/maps/layers) * Set widgets [guide](/carto-user-manual/maps/widgets) * Customize your map views [guide](/carto-user-manual/maps/map-view-modes) * Add SQL parameters [guide](/carto-user-manual/maps/sql-parameters) * Apply a mask to your map and filter out your data [guide](/carto-user-manual/maps/feature-selection-tool) * Publish and share your maps [guide](/carto-user-manual/maps/sharing-and-collaboration) # Map layout Every Builder map has a few dedicated areas, so you and your viewers always know where to find things: * **Widgets panel** on the right, with the map's widgets and description. * **Parameters bar** above the map, when the map has SQL parameters. * **Map toolbar** at the top left of the map, with the map tools. * **Map controls** in the bottom-right corner, with zoom, basemap and 3D. * **Legend** in the bottom-left corner. As an Editor, you choose how the widgets panel looks, and your choice is saved with the map. Viewers, guests and anyone with a public link see the map exactly as you set it up. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-4ca452d89894c10f5be532030c1ac52648b1c6e8%2Fbuilder-layout-tour.gif?alt=media" alt="A tour of the Builder layout"><figcaption>A tour of the Builder layout</figcaption></figure> ## Widgets panel The widgets panel shows your [widgets](/carto-user-manual/maps/widgets) and the [map description](/carto-user-manual/maps/map-description). Use the buttons in the top-right corner of the map to show or hide them. ### Layout options As an Editor, click the **Layout** button in the map toolbar to choose how the widgets panel appears: * **Columns:** show widgets in **1 column** or **2 columns** side by side. * **Floating:** turn it on to show the panel as a card over the map, so the map uses the full width. Turn it off to dock the panel next to the map. * **Dual map view:** split the map in two to compare them. Learn more in [Map view modes](/carto-user-manual/maps/map-view-modes). * **Reset layout:** goes back to the default layout, with one docked column. It also turns off dual map view and returns full-width widgets to column width. It appears once you change something. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-ab57e022603c4c0737b9323e0a2dbfb74dd97096%2Fbuilder-layout-popover.png?alt=media" alt="The Layout options"><figcaption>The Layout options</figcaption></figure> <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-c6ef4bf065e1b6180a66e7b20baa6b3a17a0598b%2Fbuilder-layout-floating-single-widget.png?alt=media" alt="A single widget floating over the map"><figcaption>A single widget floating over the map</figcaption></figure> By default, the widgets panel is docked with one column. Layout changes appear in the map's [version history](/carto-user-manual/maps/version-history), so you can go back to an earlier layout. {% hint style="info" %} You can't float the widgets panel while dual map view is on. Turning on dual map view docks the panel, and it floats again on its own when you turn dual map view off. {% endhint %} ### Full width widgets With two columns, you can give a widget the full width of the panel, for example to make a key number stand out on its own row. Open the widget's more options menu and choose **Full width**. Choose **Column width** to put it back in a single column. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-ebb4b25c339215fba3b4f3e0a4781c5c69585847%2Fbuilder-widget-full-width-menu.png?alt=media" alt="The Full width option in a widget's more options menu"><figcaption>The Full width option in a widget's more options menu</figcaption></figure> <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-23a637d8d8699330196fa442c2c9fafb209d3a5f%2Fbuilder-widget-full-width-result.png?alt=media" alt="A formula widget taking the full first row"><figcaption>A formula widget taking the full first row</figcaption></figure> If a widget ends up alone in a row, it fills the whole row, so there are no empty gaps. ### Collapsing widgets Anyone viewing the map can collapse a widget from its header to hide it. With two columns, the two widgets in a row collapse and expand together. Widgets can also collapse automatically. In the widget's Behavior settings, turn on **Collapse when no layers are visible**. The widget stays in the panel, collapsed to its header, until one of its layers is visible again. Widgets at the bottom of the map, such as the Table widget, have their own collapse control. You can keep them open while the widgets panel is hidden. ## Parameters bar When a map has [SQL parameters](/carto-user-manual/maps/sql-parameters), they appear in a bar above the map. Each one shows its name and current value, so it's clear at a glance what the map is showing. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-0c102c531995c78ee06ae06b3bfb226ace5fd14f%2Fbuilder-layout-parameters-bar.png?alt=media" alt="The parameters bar, with a Text parameter open"><figcaption>The parameters bar, with a Text parameter open</figcaption></figure> * **Reorder parameters:** as an Editor, drag a parameter by its handle to a new position. Put the most useful ones first, since they stay visible when the bar is full. * **When the bar is full:** use the arrows at the edges of the bar to see the rest. The bar only appears when the map has parameters. As an Editor, you can also hide parameter controls from viewers in [Map settings for viewers](/carto-user-manual/maps/sql-parameters/publishing-sql-parameters). ## Map toolbar The map tools are grouped in one toolbar at the top left of the map: * [Feature selection tool](/carto-user-manual/maps/feature-selection-tool) * [Measure distances](/carto-user-manual/maps/measure-distances) * [Comments](/carto-user-manual/maps/sharing-and-collaboration/comments) * [Search locations](/carto-user-manual/maps/search-locations) Editors also see the **Layout** button. Viewers see the tools you turn on in [Map settings for viewers](/carto-user-manual/maps/sharing-and-collaboration/map-settings-for-viewers), plus a button to chat with the map's [AI Agent](/carto-user-manual/ai-agents) when it has one. ## Map controls and legend Zoom, your location and the [basemap selector](/carto-user-manual/maps/basemaps/basemap-selector) are grouped in the bottom-right corner of the map. As an Editor, you'll find the 3D toggle in the basemap selector. Learn more in [Map view modes](/carto-user-manual/maps/map-view-modes). The [legend](/carto-user-manual/maps/legend) is in the bottom-left corner. Click the layers button to open it. ## Hiding the left panel As an Editor, press **Ctrl + B** (**⌘ + B** on Mac) to hide the Layers and Sources panel and give its space to the map. Press it again to bring the panel back on the tab you were using. ## Tablets and phones Maps adapt to tablets, phones and narrow embeds, keeping the map front and center. On these screens you can view and explore maps. To edit a map, use a computer. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-b71fb8fbab98b5fd425c802ce8038334ec717fa8%2Fbuilder-responsive-layout.gif?alt=media" alt="A map adapting from desktop to tablet to phone"><figcaption>A map adapting from desktop to tablet to phone</figcaption></figure> * **Tablets:** the widgets panel keeps the docked or floating layout you chose, in one column. * **Phones:** widgets and the map description open full width over the map. With dual map view, the two maps are shown one above the other. * **AI Agents:** viewers can chat with the map's [AI Agent](/carto-user-manual/ai-agents) on tablets and phones too. On a phone, the agent opens full screen with its conversation starters. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-59ebc628a1c5453f795c2691b5284cbdc111d29e%2Fbuilder-tablet-layout.png?alt=media" alt="A map on a tablet"><figcaption>A map on a tablet</figcaption></figure> <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-1712e812d123ad7e1feffd249777c457219a866b%2Fbuilder-phone-widgets-and-agent.png?alt=media" alt="A map on a phone, with the widgets and the AI Agent"><figcaption>A map on a phone, with the widgets and the AI Agent</figcaption></figure> Editing options, such as the Layers and Sources panel and widget settings, aren't shown on these screens. A notice explains this the first time you open a map, and you can choose **Do not show again**. # Data sources CARTO Builder allows you to add sources by connecting directly with your data warehouses, ensuring security and data governance. Once a source is added, the related layer associated with the source is also rendered on the map. From this point, you can start styling your layer, adding widgets, and creating your interactive application. ## Data sources types Builder currently support the following data sources types: * [**Simple features**](/carto-user-manual/maps/data-sources/simple-features): Unaggregated features using standard geometry (point, line or polygon) and attributes, ready to use in Builder. * [**Spatial Indexes**](/carto-user-manual/maps/data-sources/spatial-indexes): Aggregated data sources for improved performance or specific use cases, including Quadbin and H3 spatial indexes. * [**Pre-generated tilesets**](/carto-user-manual/maps/data-sources/pre-generated-tilesets)**:** Tilesets pre-generated using CARTO Analytics Toolbox procedures or Workflows and stored directly in your data warehouse, ideal for handling very large, static datasets. * [**Raster**](/carto-user-manual/maps/data-sources/rasters): A raster source is composed of grids of pixels, where each pixel contains a value representing specific information * **Sources without an associated layer**: These are data sources added to a map that has not associated layer. They are typically used to power widgets, SQL parameters, or AI Agents**,** enabling advanced interactivity and insights without visual clutter. You can add a layer from these sources at any time. ## Methods for adding sources In Builder, you can add data sources either as table sources by connecting to a materialized table in your data warehouse or through custom SQL queries. These queries execute directly in your data warehouse, fetching the necessary properties for your map. * **Table sources:** Connect directly to your data warehouse table through the data explorer dialog. Once connected, the data source is added including its related layer. * **SQL query sources:** Perform a custom SQL query that will act as your input source. Once you execute it, if valid, a new data source and its linked layer will be added to the Builder. {% hint style="info" %} **Best practices for SQL Query sources** SQL Editor is not designed for **conducting complex analysis** or detailed step-by-step geospatial analytics directly, as Builder executes a separate query for each map tiles. For analysis requiring high computational power, we recommend two approaches: * **Materialization**: Consider materializing the output result of your analysis. This involves saving the query result as a table in your data warehouse and use that output table as the data source in Builder. * **Workflows**: Use [CARTO Workflows](/carto-user-manual/workflows) for conducting step-by-step analysis. This allows you to process the data in stages and visualize the output results in Builder effectively. {% endhint %} ## Adding data sources To add sources in Builder, click on "Add source from" and choose from the following options: * [**Data Explorer**](#adding-a-source-from-data-explorer)**:** Browse and add tables as sources from your existing connections. * [**Custom Query (SQL):**](#adding-a-source-from-a-custom-query-sql) Write your own SQL query using the connection of your choice. * [**Import file**](#adding-source-by-importing-a-file)**:** Start the process of importing a file to a CARTO connection. You can also **drag and drop** your files directly on Builder to start the import flow. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-176da1013d8949c38eeba9c00baab2335b8f0dae%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> {% hint style="info" %} [Partitioned BigQuery tables](https://cloud.google.com/bigquery/docs/partitioned-tables) require a WHERE clause in the query filtering by the column used for the partition. If you need to load a BigQuery partitioned table in Builder, add it as a SQL Query source like: ```sql SELECT * FROM project.dataset.my_partitioned_table WHERE partition_column = 'value' ``` {% endhint %} ### **Adding a source from Data Explorer** To add a source, navigate to the desired location, select your table and click 'Add Source'. The source and its associated layer will be added to the map. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-e67c6a1147be030f1d39d304376171649ed306d6%2FScreenshot%202025-11-06%20at%2014.11.35.png?alt=media" alt=""><figcaption></figcaption></figure> {% hint style="success" %} You can star connections, database/projects/schemas and tables to quickly access them later. For more information, see [Starring items for quick access](/carto-user-manual/data-explorer#starring-items-for-quick-access). {% endhint %} ### **Adding a source from a Custom Query (SQL)** Use the SQL Editor panel in Biulder to add a source by selecting a specific connection. Create your own SQL queries to perform simple analysis, create WHERE statements to pre-filter your data, or use SQL Parameters. You can also leverage CARTO Analytics Toolbox directly from this interface. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-857a7daa5e32f2fb0b2e32e24f6fee84557089e3%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> ### **Adding source by importing a file** CARTO allows creating tables in your connections by importing files from your computer or via URL. Once a file is imported, the resulting table can be previewed in Data Explorer and used in Builder and external applications. {% hint style="success" %} You can also **drag and drop** files directly on Builder to start the import flow. {% endhint %} <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-6616b32f18fd9ffa7282ebbac8f9e5b2dc445cca%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> {% hint style="info" %} Find more information about compatible data warehouses, supported formats, column names, and delimiters in our [Importing Data](/carto-user-manual/data-explorer/importing-data) documentation. {% endhint %} # Simple features Builder supports simple features stored as geometry or geography in cloud data warehouses. These simple features are defined as a standard which specifies digital storage of geographical data, usually point, line or polygon, storing both spatial and non-spatial features. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-f5ca8788bbd30878af125e427ba666e1dbde7e29%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> ## Supported spatial column types CARTO identifies the geo column of a source from the column type reported by the data warehouse. This table shows the type of simple features (`geography` or `geometry`) supported on each data warehouse: | | **Geography** | **Geometry** | | ------------------------ | ------------- | ------------- | | **BigQuery** | ✅ | Not Supported | | **CARTO Data Warehouse** | ✅ | Not Supported | | **Snowflake** | ✅ | Not Supported | | **Databricks** | Not Supported | ✅ | | **Amazon Redshift** | Not Supported | ✅ | | **PostgreSQL** | Not Supported | ✅ | | **Oracle** | Not Supported | ✅ | Geometries stored in **text columns** (WKT, GeoJSON) or in **generic binary columns** (WKB in a `BYTES`, `BINARY`, `VARBYTE` or `BYTEA` column) are not detected as geo columns. Cast them to the spatial type of your data warehouse in the SQL Query of your source, or materialize a table with a proper spatial column. {% hint style="info" %} **Converting between geography and geometry** If your column uses the type that is not supported by your provider, you can convert it: * **Snowflake:** convert `GEOMETRY` to `GEOGRAPHY`, for example with the [Geometry to Geography](/carto-user-manual/workflows/components/data-preparation#geometry-to-geography) component in Workflows. * **Amazon Redshift** and **PostgreSQL:** convert `GEOGRAPHY` to `GEOMETRY`, for example with the [Geography to Geometry](/carto-user-manual/workflows/components/data-preparation#geography-to-geometry) component in Workflows. {% endhint %} ### Coordinate reference systems | | **Projection support** | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **BigQuery**, **CARTO Data Warehouse**, **Snowflake** | `GEOGRAPHY` values are always WGS84 (`EPSG:4326`). Nothing to configure. | | **Databricks** | Coordinates are expected to be WGS84 (`EPSG:4326`) longitude/latitude. CARTO does not reproject Databricks geometries, so data in another projection will not display correctly. | | **PostgreSQL**, **Amazon Redshift**, **Oracle** | Any SRID is supported as long as it is set on the geometries. CARTO reads the SRID from the data and reprojects on the fly when needed. If the SRID is unset (`0`), WGS84 is assumed. | Reprojecting on every tile request has a cost. For the best performance, store your geometries in the projection recommended for each data warehouse and make sure the SRID is set — check the [performance considerations](/carto-user-manual/maps/performance-considerations) section for details. ## Limitations {% hint style="info" %} When working with simple features in Builder, ensure that your spatial column contains only a single type of geometry—either points, lines, or polygons. Mixing different geometry types within the same spatial column is not supported. To handle multiple geometry types, use separate sources for each type. The single-part and multi-part variants of the same family can be mixed: `POINT`/`MULTIPOINT` are both rendered as points, `LINESTRING`/`MULTILINESTRING` as lines, and `POLYGON`/`MULTIPOLYGON` as polygons. {% endhint %} {% hint style="warning" %} **GEOMETRYCOLLECTION is not supported** If your data contains GEOMETRYCOLLECTION geometry types, you'll need to convert them to individual geometry components before visualization. Use the ST\_Dump function in your SQL query to explode geometry collections. {% endhint %} {% hint style="warning" %} **Provider-specific limitations** * **Oracle:** only two-dimensional `SDO_GEOMETRY` values are supported (`SDO_GTYPE` `2001`, `2002`, `2003` and `2007`). Geometries with a Z or M dimension are not supported. * **Databricks:** native `GEOMETRY` and `GEOGRAPHY` types require Databricks Runtime 17.1 or above (Spark 4.0.0), which is a [requirement for creating a Databricks connection](/carto-user-manual/connections/databricks#setup-requirements). Legacy Databricks connections instead store geometries as WKB in binary columns and need the [Prepare for Visualization](/carto-user-manual/workflows/components/spatial-operations#prepare-for-visualization) component before they can be visualized. {% endhint %} ## Visualizing simple features Builder ensures performance experience when rendering simple features on a map as data is loaded progressively via vector tiles. The data for these tiles is extracted by pushing down SQL queries to the data warehouse, and they are requested as you zoom in and out or pan the map. Note these queries in Builder are cached. To understand more how caching works and different methods to keep your data fleshed, check this link in our [documentation](/carto-user-manual/maps/data-sources/managing-data-freshness). Find more information about performance consideration for this data source type in [this section](/carto-user-manual/maps/performance-considerations). # Spatial Indexes The CARTO platform natively supports spatial indexes, enabling you to leverage their capabilities when working with large-scale data directly in your data warehouse. Spatial indexes are excellent for large-scale analytics and visualization. Using Builder, you can create stunning and powerful visualizations by connecting directly to these types of sources. The supported spatial index formats are quadbins and H3. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-b9e3c7be9a6a2c6ecee0a9751fee5797aa76858d%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> Based on Discrete Global Grid (DGG) systems, spatial indexes reference each cell of the grid. Think of a spatial index as an id that always makes reference to the same portion of the surface on Earth. * This portion of the Earth is called a **cell**. * The shape of the cell depends on the **type of index**. For example, H3 uses hexagons; while Quadbin uses square. * The size of the cell depends on the **resolution**. The higher the resolution, the smaller the size of the cell. DGG systems are hierarchical, which means that every cell contains a constant number of smaller cells at a higher resolution: <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-f9850a3a8ef5e39d4f67f274582d3b42444104e5%2Fimage.png?alt=media" alt=""><figcaption>Example of how each H3 cell is sub-divided into smaller cells at higher resolutions.</figcaption></figure> ## Advantages of working with spatial indexes One of the advantages of working with spatial indexes is that operating with them in data warehouses is way more efficient and cost-effective than computing geometries. They are also smaller in size and help saving storage and reducing the volume of transferred data. When working with spatial indexes, Builder will dynamically aggregate your data into cells at a meaningful resolution depending on the current map zoom level. See the animation below for an example: <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-73857e306c2476705e2e37b8a20a5556bdf25fff%2Fh3_aggregation.gif?alt=media" alt=""><figcaption></figcaption></figure> ## Visualizing spatial index sources Your spatial index source must contain a column storing the spatial index identifier. Below is an example table containing h3 indexes, with some additional columns that contain aggregated socio-demographic data for each hexagon: | h3 | population | avg\_rent | | --------------- | ---------- | --------- | | 8a0c0036a49ffff | 103.0 | 1344.56 | | 8a0c002e4c0ffff | 1093.0 | 2087.04 | | 8a0c002e4caffff | 209.0 | 3098.39 | The `h3` column contains the indexes for H3 cells at level 10. That’s what we call the *native resolution of the data*. When you load a source in Builder, data is aggregated dynamically as you zoom in an out. This aggregation will be generated on the fly, using SQL queries that are pushed from CARTO into the data warehouse. When visualizing a spatial index source in Builder, you can control the aggregation size, to define how granular you'd like the aggregation to be when navigating through the map as part of the layer styling configuration. Learn more in this section. To understand more about performance and processing cost optimizations that should be applied to this specific source type, check [this section](/carto-user-manual/maps/performance-considerations). # Pre-generated tilesets Pre-generated tilesets are sources with tiles that have been previously generated using either the [CARTO Analytics Toolbox](/data-and-analysis/analytics-toolbox-for-bigquery/key-concepts/tilesets) or [Workflows](/carto-user-manual/workflows/components/tileset-creation). Both the creation and storage of these tilesets occur in the data warehouse. This type of data source is ideal for managing very large, static datasets. They are efficient, cost-effective, and provide high-performance visualization. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-8e3d36be4bafb6487f53d0187323ce2850c81a2c%2Fpre-generated%20tilesets.gif?alt=media" alt=""><figcaption></figcaption></figure> ## Visualizing pre-generated tilesets Builder supports the visualization of the four types of pre-generated tilesets: * **Vector Tilesets:** Pre-generated tilesets processed from point, line, or polygon tables for smooth, interactive maps. * **Point Aggregation Tilesets**: These tilesets aggregate point data with their properties into tilesets, perfect for visualizing dense point clusters. * **Quadbin Aggregation Tilesets**: Aggregated grid for scallable hierarchy management. * **H3 Aggregation Tilesets:** Aggregate quadbin indices into tilesets for scallable spatial hierarcy management. To ensure optimizal visualization and performance, you must make use of the different parameters that allow you to have full-control of the tileset specification. To learn more about this type of source in terms of performance consideration, review this [section](/carto-user-manual/maps/performance-considerations). # Rasters Raster data is composed of grids of pixels, where each pixel contains a value representing specific information, such as temperature, elevation, or vegetation indices. These datasets can represent continuous surfaces or sparse data with defined no-data regions. The CARTO platform provides seamless tools for importing, analyzing and visualizing raster sources directly in your data warehouse. <figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-46648dd22e1d32982606a7655ffb597b9547726c%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> ## Visualizing rasters To visualize raster sources, they must first be stored in your data warehouse using the **CARTO raster loader**. This tool ensures your raster files are properly uploaded and formatted for seamless integration with the CARTO platform. [Learn more about preparing and uploading your raster data](/carto-user-manual/data-explorer/importing-data/importing-rasters). To optimize performance, raster sources should include **overviews**—lower-resolution versions of the raster data—enabling efficient visualization at different zoom levels. Additionally, if your raster source contains a **color interpreter** (e.g., palette, grayscale, or RGB), CARTO will automatically apply default styling based on the metadata, making it easier to quickly render the raster on your map. {% hint style="warning" %} Note the current limitations and specific requirements for raster sources: * Raster sources cannot be queried directly through SQL functions, meaning they are not compatible with **SQL Editor** or **SQL Parameters**. This is similar to the behavior of pre-generated tilesets. * Raster sources are currently supported for **Google BigQuery, Snowflake and Databricks** environments. {% endhint %} --- [Next Page](https://docs.carto.com/llms-full.txt/1)