Activity Data API

Export activity and API usage data.

Export what happened in your organization — who did what, and how much API usage it drove — as CSV or Parquet, for auditing or for loading into your own analytics.

Request a range, poll the job, then download from the returned URLs before they expire.

Endpoint	What it does
POST /activity-data-jobs	Create an activity data job
GET /activity-data-jobs/{jobId}	Get an activity data job
DELETE /activity-data-jobs/{jobId}/cancel	Cancel an activity data job

These endpoints live on the accounts host — https://accounts.app.carto.com — not on your regional API Base URL, and their paths have no /v3 prefix.

These endpoints need an OAuth Access Token from an Admin or Superadmin user. See Authorization.

Picking a time range

The range must be under 60 days, start after your account was created, and end no later than the most recent ready data. Data for a day becomes available at 05:00 UTC the following day, so a range ending today usually fails until then.

For a longer history, request consecutive ranges and stitch the exports together.

Endpoints

Create an activity data job

post

Exports your organization's activity data for a time range.

The job runs asynchronously — poll GET /activity-data-jobs/{jobId} until status is success, then use the returned download URLs.

Note this endpoint lives on the accounts host, not on your regional API base URL, and there is no /v3 in the path.

Requires the Admin or Superadmin role.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Body

application/json

formatstring · enumRequiredPossible values:

startTimestringRequired

Start of the range. Must be after your account was created.

endTimestringRequired

End of the range. Must be after startTime, and can't be in the future or cover data that isn't ready yet. The range must be under 60 days.

Responses

201

The job was created.

application/json

idstringOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

You aren't an admin, or activity data isn't available for your account.

application/json

post/activity-data-jobs

HTTPcURLJavaScriptPython

POST /activity-data-jobs HTTP/1.1
Host: accounts.app.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 127

{
  "categories": [
    "activity",
    "apiUsage"
  ],
  "format": "csv",
  "startTime": "2026-06-27 00:00:00 UTC",
  "endTime": "2026-06-29 00:00:00 UTC"
}

{
  "id": "e38163e9-37f3-4269-b400-c7b160325bce"
}

Get an activity data job

get

Returns the state of an activity data job. When status is success the response includes the download URLs and their expiry.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

jobIdstringRequired

The job identifier.

Example: e38163e9-37f3-4269-b400-c7b160325bce

Responses

200

The job.

application/json

An activity data export job. downloadUrls and downloadUrlsExpirationDate are only present when status is success; errorMessage only when it is failure.

idstringOptional

statusstring · enumOptionalPossible values:

formatstring · enumOptionalPossible values:

startTimestring · date-timeOptional

endTimestring · date-timeOptional

createdAtstring · date-timeOptional

downloadUrlsExpirationDatestring · date-timeOptional

errorMessagestringOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

404

The resource doesn't exist.

application/json

get/activity-data-jobs/{jobId}

HTTPcURLJavaScriptPython

GET /activity-data-jobs/{jobId} HTTP/1.1
Host: accounts.app.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "e38163e9-37f3-4269-b400-c7b160325bce",
  "status": "success",
  "downloadUrls": {
    "activity": [
      "https://storage.googleapis.com/carto-acc-us-east1-1-export-storage/activity-0.csv"
    ],
    "apiUsage": [
      "https://storage.googleapis.com/carto-acc-us-east1-1-export-storage/api-usage-0.csv"
    ]
  },
  "downloadUrlsExpirationDate": "2026-08-02T11:26:14.125Z",
  "categories": [
    "activity",
    "apiUsage"
  ],
  "startTime": "2026-07-23T00:00:00.000Z",
  "endTime": "2026-07-24T00:00:00.000Z",
  "format": "csv",
  "createdAt": "2026-07-26T11:26:03.121Z"
}

Cancel an activity data job

delete

Cancels a job that is still pending or running. Cancelling a finished job returns 400.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

jobIdstringRequired

The job identifier.

Example: e38163e9-37f3-4269-b400-c7b160325bce

Responses

200

The cancelled job.

application/json

An activity data export job. downloadUrls and downloadUrlsExpirationDate are only present when status is success; errorMessage only when it is failure.

idstringOptional

statusstring · enumOptionalPossible values:

formatstring · enumOptionalPossible values:

startTimestring · date-timeOptional

endTimestring · date-timeOptional

createdAtstring · date-timeOptional

downloadUrlsExpirationDatestring · date-timeOptional

errorMessagestringOptional

400

The job already finished and can't be cancelled.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

404

The resource doesn't exist.

application/json

delete/activity-data-jobs/{jobId}/cancel

HTTPcURLJavaScriptPython

DELETE /activity-data-jobs/{jobId}/cancel HTTP/1.1
Host: accounts.app.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "status": "pending",
  "categories": [
    "activity"
  ],
  "format": "csv",
  "startTime": "2026-08-09T08:47:03.669Z",
  "endTime": "2026-08-09T08:47:03.669Z",
  "createdAt": "2026-08-09T08:47:03.669Z",
  "downloadUrls": {
    "ANY_ADDITIONAL_PROPERTY": [
      "https://example.com"
    ]
  },
  "downloadUrlsExpirationDate": "2026-08-09T08:47:03.669Z",
  "errorMessage": "text"
}