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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.carto.com/carto-for-agents/cli/command-reference/activity.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.