# Amplitude on boxd

> Amplitude gives you the self-serve tools and real-time data to make products and experiences that win no matter what.

- Page: https://boxd.sh/integrations/amplitude/
- CLI: `run amplitude` (54 commands, 20 marked common)
- SDK: `import { amplitude } from "@boxd/run"`; every parameter and response type is at `@boxd/run/amplitude`
- Triggers: none
- Connect: `run auth amplitude` (API key), or https://app.boxd.sh/integrations/detail/amplitude
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth amplitude      # once: prints a link to connect your account
run amplitude           # list its commands
run amplitude list-cohorts
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { every, amplitude } from "@boxd/run";

every("1 hour", async () => {
  const result = await amplitude.listCohorts({});
  console.log(result);
});
```

Run it with `run amplitude.run.ts`. Amplitude has no triggers; `every()` polls on a schedule, keeps the script running as a job, and wakes the machine when it is due.

## Commands

Required flags are listed; `run amplitude <command> --help` lists the optional ones. "common" marks what `run amplitude` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `assign-annotations-to-category` | `amplitude.assignAnnotationsToCategory()` | `--annotation-ids` `--category-id` | 0 | Bulk assign multiple annotations to a category in Amplitude |
| `cancel-deletion` ·common | `amplitude.cancelDeletion()` | `--amplitude-id` `--job-start-day` | 0 | Cancel a pending user deletion request in Amplitude |
| `check-cohort-status` ·common | `amplitude.checkCohortStatus()` | `--request-id` | 0 | Check the status of a cohort export request |
| `create-annotation` | `amplitude.createAnnotation()` | `--label` `--start` | 4 | Create a chart annotation in Amplitude to mark important dates |
| `create-annotation-category` | `amplitude.createAnnotationCategory()` | `--category` | 0 | Create an annotation category in Amplitude to organize annotations |
| `create-event-category` | `amplitude.createEventCategory()` | `--category-name` | 0 | Create a new event category in Amplitude |
| `create-event-type` | `amplitude.createEventType()` | `--event-type` | 9 | Create a new event type in Amplitude |
| `create-release` | `amplitude.createRelease()` | `--release-start` `--version` | 3 | Create a release to document product changes |
| `delete-annotation` | `amplitude.deleteAnnotation()` | `--annotation-id` | 0 | Delete a chart annotation from Amplitude |
| `delete-annotation-category` | `amplitude.deleteAnnotationCategory()` | `--category-id` | 0 | Delete an annotation category from Amplitude |
| `delete-event-category` | `amplitude.deleteEventCategory()` | `--category-id` | 0 | Delete an event category from Amplitude |
| `delete-event-type` | `amplitude.deleteEventType()` | `--event-type` | 0 | Delete an event type from Amplitude |
| `delete-users` | `amplitude.deleteUsers()` | `--requester` | 5 | Submit user deletion requests for GDPR/CCPA compliance |
| `download-cohort-file` ·common | `amplitude.downloadCohortFile()` | `--request-id` | 0 | Download the cohort file after request is complete |
| `find-user` ·common | `amplitude.findUser()` | `--user` | 0 | Search for users in Amplitude by canonical identifier (Amplitude ID, device ID, user ID, or user ID prefix) |
| `get-active-users` ·common | `amplitude.getActiveUsers()` | `--end` `--start` | 4 | Get the number of active or new users for a date range with optional segmentation |
| `get-annotation` | `amplitude.getAnnotation()` | `--annotation-id` | 0 | Get a single chart annotation by ID from Amplitude |
| `get-annotation-category` | `amplitude.getAnnotationCategory()` | `--category-id` | 0 | Get a single annotation category by ID from Amplitude |
| `get-cohort` ·common | `amplitude.getCohort()` | `--cohort-id` | 2 | Get a single cohort by ID and initiate download |
| `get-deletion-requests` | `amplitude.getDeletionRequests()` | `--end-day` `--start-day` | 0 | Get the status of user deletion requests within a date range |
| `get-event-categories` | `amplitude.getEventCategories()` | — | 1 | Get event categories from Amplitude |
| `get-event-property` | `amplitude.getEventProperty()` | `--property` | 1 | Get a specific event property from Amplitude taxonomy |
| `get-event-segmentation` | `amplitude.getEventSegmentation()` | `--e` `--end` `--start` | 3 | Get event segmentation data from Amplitude Analytics API |
| `get-event-type` | `amplitude.getEventType()` | `--event-type` | 0 | Get a specific event type from Amplitude by name |
| `get-event-types` | `amplitude.getEventTypes()` | — | 1 | Get all event types from Amplitude |
| `get-funnel-data` ·common | `amplitude.getFunnelData()` | `--end` `--events` `--start` | 6 | Get funnel analysis data showing user conversion through a sequence of events |
| `get-realtime-active-users` ·common | `amplitude.getRealtimeActiveUsers()` | — | 1 | Get real-time active users count from Amplitude |
| `get-retention` ·common | `amplitude.getRetention()` | `--end` `--re` `--se` `--start` | 5 | Get user retention analysis showing how users return over time after a starting action |
| `get-revenue-ltv` | `amplitude.getRevenueLtv()` | `--end` `--start` | 2 | Get revenue lifetime value (LTV) metrics including ARPU, ARPPU, and total revenue |
| `get-session-average` ·common | `amplitude.getSessionAverage()` | `--end` `--start` | 0 | Get average session length (in seconds) for a specified date range from Amplitude |
| `get-session-length` ·common | `amplitude.getSessionLength()` | `--end` `--start` | 4 | Retrieve session length distribution data for a specified date range from Amplitude |
| `get-sessions-per-user` | `amplitude.getSessionsPerUser()` | `--end` `--start` | 0 | Get average number of sessions per user for each day in a date range from Amplitude |
| `get-user-activity` ·common | `amplitude.getUserActivity()` | `--user` | 3 | Fetch a single user's profile summary and event stream by Amplitude ID |
| `get-user-composition` ·common | `amplitude.getUserComposition()` | `--end` `--p` `--start` | 0 | Get user composition breakdown by property (platform, version, country, etc.) |
| `get-user-mappings` ·common | `amplitude.getUserMappings()` | `--user-ids` | 0 | Get the list of user mappings for provided user IDs |
| `get-user-property` | `amplitude.getUserProperty()` | `--user-property` | 0 | Get a specific user property from Amplitude taxonomy |
| `identify` ·common | `amplitude.identify()` | `--identification` | 1 | Update user properties using Amplitude's Identify API |
| `list-annotation-categories` | `amplitude.listAnnotationCategories()` | — | 1 | List all annotation categories from Amplitude |
| `list-annotations` | `amplitude.listAnnotations()` | — | 4 | Get all chart annotations with optional filtering by category, chart, and date range |
| `list-cohorts` ·common | `amplitude.listCohorts()` | — | 1 | List all discoverable cohorts for an Amplitude project |
| `list-event-properties` | `amplitude.listEventProperties()` | — | 2 | Get all event properties from Amplitude, optionally filtered by event type or property name |
| `list-events` | `amplitude.listEvents()` | — | 0 | Get a list of all event types in your Amplitude project with current week's statistics |
| `list-user-properties` | `amplitude.listUserProperties()` | — | 0 | Get all user properties in your Amplitude project |
| `map-user` ·common | `amplitude.mapUser()` | `--mappings` | 1 | Map users with different user IDs together (alias/merge users) in Amplitude |
| `restore-event-type` | `amplitude.restoreEventType()` | `--event-type` | 0 | Restore a deleted event type in Amplitude |
| `send-events` ·common | `amplitude.sendEvents()` | `--events` | 2 | Send events to Amplitude using the HTTP V2 API |
| `set-group-properties` ·common | `amplitude.setGroupProperties()` | `--identification` | 1 | Set group properties for account-level reporting without sending an event |
| `update-annotation` | `amplitude.updateAnnotation()` | `--annotation-id` | 6 | Update an existing chart annotation in Amplitude |
| `update-annotation-category` | `amplitude.updateAnnotationCategory()` | `--category` `--category-id` | 0 | Update an annotation category in Amplitude |
| `update-cohort-membership` | `amplitude.updateCohortMembership()` | `--cohort-id` `--memberships` | 2 | Incrementally update cohort membership by adding or removing IDs |
| `update-event-category` | `amplitude.updateEventCategory()` | `--category-id` `--category-name` | 0 | Update an existing event category in Amplitude |
| `update-event-type` | `amplitude.updateEventType()` | `--event-type` | 11 | Update an existing event type in Amplitude |
| `upload-batch-events` ·common | `amplitude.uploadBatchEvents()` | `--events` | 2 | Bulk upload events to Amplitude using the Batch Event Upload API |
| `upload-cohort` | `amplitude.uploadCohort()` | `--app-id` `--id-type` `--ids` `--name` `--owner` `--published` | 1 | Generate a new cohort or update an existing cohort by uploading user IDs or Amplitude IDs |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.