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).

# 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 activity export

Export raw activity data to files. Useful for loading into your own data warehouse for advanced analytics, or for archiving.

# 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.