# Amplitude

> Send events and user properties to Amplitude, query your product metrics, and annotate the charts.

App · Analytics · 20 actions. Web page: https://docs.lodol.com/docs/integrations/amplitude

## Actions

### Create annotation

Mark a date on every Amplitude chart with a label, so a release, an outage or a campaign shows up next to its effect on the numbers. Point it at one chart, or leave it on all of them.

**Inputs**

- Label (`label`, text, required): The short text shown on the chart.
- Date (`start`, date, required): The day the annotation marks.
- End date (`end`, date): Leave empty for a single day, or set it to mark a period.
- Details (`details`, text): Longer text shown when someone opens the annotation.
- Category (`category`, text): Name of the annotation category to file it under, such as Releases. Leave empty for none.
- Chart (`chart_id`, text): Id of a single chart to attach it to - the last part of the chart's URL. Leave empty to show it on every chart.

**Outputs**

- `annotation` (object)
- `annotation_id` (number): The new annotation's id
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "annotation": {
    "category": {
      "id": 12,
      "name": "Releases"
    },
    "chart_id": null,
    "details": "Shipped to 100% of traffic",
    "end": null,
    "id": 4821,
    "label": "Pricing page redesign",
    "start": "2026-09-01"
  },
  "annotation_id": 4821,
  "status": "success"
}
```

### Delete annotation

Remove a chart annotation for good. Takes the annotation's numeric id.

**Inputs**

- Annotation (`annotation_id`, number, required): The annotation's numeric id. Use List annotations to find one.

**Outputs**

- `annotation_id` (number): The annotation that was deleted
- `deleted` (true/false): True once it is gone
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "annotation_id": 4821,
  "deleted": true,
  "status": "success"
}
```

### Get active users

Count active or new users per day, week or month, optionally broken down by a property. The headline number behind DAU, WAU and MAU.

**Inputs**

- From (`start_date`, date): First day to include. Leave both dates empty to read the last 30 days.
- To (`end_date`, date): Last day to include. Leave both dates empty to read the last 30 days.
- Count (`metric`, text): Active users or new users. Defaults to active. One of: `active` (Active users), `new` (New users).
- Count by (`interval`, text): How finely to bucket the result over time. Defaults to daily. One of: `1` (Daily), `7` (Weekly), `30` (Monthly).
- Break down by (`group_by`, text): Name of a property to split the result by, such as country or platform. Prefix a custom user property with 'gp:'. Leave empty for one combined series.

**Outputs**

- `data` (object)
- `end` (text): Last day read, as YYYYMMDD
- `start` (text): First day read, as YYYYMMDD
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "data": {
    "series": [
      [
        128,
        141
      ]
    ],
    "seriesMeta": [
      {
        "segmentIndex": 0
      }
    ],
    "xValues": [
      "2026-08-06",
      "2026-08-07"
    ]
  },
  "end": "20260904",
  "start": "20260806",
  "status": "success"
}
```

### Get annotation

Read one chart annotation by its id: its label, details, dates, category and the chart it belongs to.

**Inputs**

- Annotation (`annotation_id`, number, required): The annotation's numeric id. Use List annotations to find one.

**Outputs**

- `annotation` (object)
- `annotation_id` (number): The annotation's id
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "annotation": {
    "category": {
      "id": 12,
      "name": "Releases"
    },
    "chart_id": null,
    "details": "Shipped to 100% of traffic",
    "end": null,
    "id": 4821,
    "label": "Pricing page redesign",
    "start": "2026-09-01"
  },
  "annotation_id": 4821,
  "status": "success"
}
```

### Get average session length

Read the average length of a session, in seconds, for each day in the window. Use it to see whether a change made people stay longer.

**Inputs**

- From (`start_date`, date): First day to include. Leave both dates empty to read the last 30 days.
- To (`end_date`, date): Last day to include. Leave both dates empty to read the last 30 days.

**Outputs**

- `data` (object)
- `end` (text): Last day read, as YYYYMMDD
- `start` (text): First day read, as YYYYMMDD
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "data": {
    "series": [
      [
        128,
        141
      ]
    ],
    "seriesMeta": [
      {
        "segmentIndex": 0
      }
    ],
    "xValues": [
      "2026-08-06",
      "2026-08-07"
    ]
  },
  "end": "20260904",
  "start": "20260806",
  "status": "success"
}
```

### Get average sessions per user

Read how many sessions the average user starts each day. Use it alongside session length to tell 'people come back more often' from 'people stay longer'.

**Inputs**

- From (`start_date`, date): First day to include. Leave both dates empty to read the last 30 days.
- To (`end_date`, date): Last day to include. Leave both dates empty to read the last 30 days.

**Outputs**

- `data` (object)
- `end` (text): Last day read, as YYYYMMDD
- `start` (text): First day read, as YYYYMMDD
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "data": {
    "series": [
      [
        128,
        141
      ]
    ],
    "seriesMeta": [
      {
        "segmentIndex": 0
      }
    ],
    "xValues": [
      "2026-08-06",
      "2026-08-07"
    ]
  },
  "end": "20260904",
  "start": "20260806",
  "status": "success"
}
```

### Get event segmentation

Count how often an event happens over time - unique users, total events, share of daily active users, or average per user - optionally broken down by a property. This is Amplitude's Event Segmentation chart as data.

**Inputs**

- Event (`event_type`, text, required): The event to measure. Pick one of the project's events, or use [Amplitude] Any Active Event to count every event.
- From (`start_date`, date): First day to include. Leave both dates empty to read the last 30 days.
- To (`end_date`, date): Last day to include. Leave both dates empty to read the last 30 days.
- Measure (`metric`, text): What to count. Defaults to unique users. One of: `uniques` (Unique users), `totals` (Total events), `pct_dau` (Percent of daily active users), `average` (Average events per user).
- Which users (`user_type`, text): Count all active users, or only users new in the window. One of: `active` (All active users), `new` (New users only).
- Count by (`interval`, text): How finely to bucket the result over time. Defaults to daily. Amplitude will not spread real-time or hourly buckets over a long range, so picking one of those shortens the default window to 3 days (real-time) or 9 days (hourly). One of: `-300000` (Real-time (5 minutes)), `-3600000` (Hourly), `1` (Daily), `7` (Weekly), `30` (Monthly).
- Break down by (`group_by`, text): Name of a property to split the result by, such as country or platform. Prefix a custom user property with 'gp:'. Leave empty for one combined series.
- How many breakdown values (`limit`, number): How many 'Break down by' values to return. Ignored when nothing is broken down. Defaults to 100. From 1 to 1000. Default: `100`.

**Outputs**

- `data` (object)
- `end` (text): Last day read, as YYYYMMDD
- `event_type` (text): The event that was measured
- `start` (text): First day read, as YYYYMMDD
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "data": {
    "series": [
      [
        128,
        141
      ]
    ],
    "seriesMeta": [
      {
        "segmentIndex": 0
      }
    ],
    "xValues": [
      "2026-08-06",
      "2026-08-07"
    ]
  },
  "end": "20260904",
  "event_type": "Invoice Paid",
  "start": "20260806",
  "status": "success"
}
```

### Get funnel analysis

Measure how many users get from one event to the next through a sequence of steps, and where they drop off. Returns the conversion rate and user count at each step, plus how long the median and average user took to get there.

**Inputs**

- Steps (`events`, list, required): The events that make up the funnel, in order. At least two. Use List events to find the exact names.
- From (`start_date`, date): First day to include. Leave both dates empty to read the last 30 days.
- To (`end_date`, date): Last day to include. Leave both dates empty to read the last 30 days.
- Steps must happen (`mode`, text): How strictly to require the order. Defaults to in this order. One of: `ordered` (In this order), `unordered` (In any order), `sequential` (In this order with nothing in between).
- Which users (`user_type`, text): Count all active users, or only users new in the window. One of: `active` (All active users), `new` (New users only).
- Count by (`interval`, text): How finely to bucket the result over time. Defaults to daily. Amplitude will not spread real-time or hourly buckets over a long range, so picking one of those shortens the default window to 3 days (real-time) or 9 days (hourly). One of: `-300000` (Real-time (5 minutes)), `-3600000` (Hourly), `1` (Daily), `7` (Weekly), `30` (Monthly).
- Break down by (`group_by`, text): Name of a property to split the result by, such as country or platform. Prefix a custom user property with 'gp:'. Leave empty for one combined series.
- Conversion window (seconds) (`conversion_window_seconds`, number): How long a user has to finish the funnel. Defaults to 2592000 (30 days). At least 1.
- How many breakdown values (`limit`, number): How many 'Break down by' values to return. Ignored when nothing is broken down. Defaults to 100. From 1 to 1000. Default: `100`.

**Outputs**

- `count` (number): Segments returned
- `end` (text): Last day read, as YYYYMMDD
- `segments` (list)
- `start` (text): First day read, as YYYYMMDD
- `status` (text): Status of the action execution ("success" on success).
- `steps` (list): The funnel's events, in order

**Example output**

```json
{
  "count": 1,
  "end": "20260904",
  "segments": [
    {
      "avgTransTimes": [
        0,
        2175406
      ],
      "cumulative": [
        1.0,
        0.42
      ],
      "cumulativeRaw": [
        980,
        412
      ],
      "events": [
        "Sign Up",
        "Invoice Paid"
      ],
      "medianTransTimes": [
        0,
        166444
      ],
      "meta": {
        "segmentIndex": 0
      },
      "stepByStep": [
        1.0,
        0.42
      ]
    }
  ],
  "start": "20260806",
  "status": "success",
  "steps": [
    "Sign Up",
    "Invoice Paid"
  ]
}
```

### Get real-time active users

Read how many users are active right now, minute by minute, with yesterday alongside for comparison. Takes no date range - Amplitude always reports the last two days.

**Inputs**: None.

**Outputs**

- `data` (object)
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "data": {
    "series": [
      [
        41,
        38
      ],
      [
        37,
        40
      ]
    ],
    "seriesLabels": [
      "Today",
      "Yesterday"
    ],
    "xValues": [
      "09:00",
      "09:05"
    ]
  },
  "status": "success"
}
```

### Get retention analysis

Measure how many users come back after a starting action, day by day, week by week or month by month. Defaults to new users returning for anything at all, which is the standard retention curve.

**Inputs**

- Started with (`start_event`, text): The action that puts a user in the cohort. Defaults to [Amplitude] New User.
- Came back for (`return_event`, text): What counts as coming back. Defaults to [Amplitude] Any Event.
- From (`start_date`, date): First day to include. Leave both dates empty to read the last 30 days.
- To (`end_date`, date): Last day to include. Leave both dates empty to read the last 30 days.
- Count a return as (`retention_mode`, text): How to decide a user was retained. Defaults to N-day. One of: `nday` (N-day (came back on exactly that day)), `rolling` (Rolling (came back on that day or later)), `bracket` (Bracket (custom day ranges)), `nday_or_before` (N-day or before (came back by that day)).
- Day ranges (`brackets`, text): Only for bracket mode: the day ranges to group returns into, such as [[0,4],[4,8]].
- Count by (`interval`, text): How finely to bucket the result over time. Defaults to daily. One of: `1` (Daily), `7` (Weekly), `30` (Monthly).
- Break down by (`group_by`, text): Name of a property to split the result by, such as country or platform. Prefix a custom user property with 'gp:'. Leave empty for one combined series.

**Outputs**

- `data` (object)
- `end` (text): Last day read, as YYYYMMDD
- `return_event` (text): What counted as coming back
- `start` (text): First day read, as YYYYMMDD
- `start_event` (text): The action that defined the cohort
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "data": {
    "series": [
      {
        "combined": [
          {
            "count": 128,
            "incomplete": false,
            "outof": 128
          },
          {
            "count": 71,
            "incomplete": false,
            "outof": 128
          }
        ],
        "dates": [
          "Aug 6",
          "Aug 7"
        ],
        "values": {
          "Aug 6": [
            {
              "count": 128,
              "incomplete": false,
              "outof": 128
            },
            {
              "count": 71,
              "incomplete": false,
              "outof": 128
            }
          ]
        }
      }
    ],
    "seriesMeta": [
      {
        "eventIndex": 0,
        "segmentIndex": 0
      }
    ]
  },
  "end": "20260904",
  "return_event": "_all",
  "start": "20260806",
  "start_event": "_new",
  "status": "success"
}
```

### Get revenue lifetime value

Read revenue per user over their lifetime: average revenue per user, per paying user, total revenue, or the number of paying users. Needs revenue on your events to return anything.

**Inputs**

- From (`start_date`, date): First day to include. Leave both dates empty to read the last 30 days.
- To (`end_date`, date): Last day to include. Leave both dates empty to read the last 30 days.
- Measure (`metric`, text): Which revenue figure to read. Defaults to ARPU. One of: `0` (ARPU - average revenue per user), `1` (ARPPU - average revenue per paying user), `2` (Total revenue), `3` (Paying users).
- Count by (`interval`, text): How finely to bucket the result over time. Defaults to daily. One of: `1` (Daily), `7` (Weekly), `30` (Monthly).
- Break down by (`group_by`, text): Name of a property to split the result by, such as country or platform. Prefix a custom user property with 'gp:'. Leave empty for one combined series.

**Outputs**

- `data` (object)
- `end` (text): Last day read, as YYYYMMDD
- `start` (text): First day read, as YYYYMMDD
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "data": {
    "series": [
      [
        128,
        141
      ]
    ],
    "seriesMeta": [
      {
        "segmentIndex": 0
      }
    ],
    "xValues": [
      "2026-08-06",
      "2026-08-07"
    ]
  },
  "end": "20260904",
  "start": "20260806",
  "status": "success"
}
```

### Get session length distribution

Read how session lengths are spread across buckets - how many sessions lasted 0-60 seconds, 60-120, and so on. Set the bucket unit and size, or leave them empty for Amplitude's own.

**Inputs**

- From (`start_date`, date): First day to include. Leave both dates empty to read the last 30 days.
- To (`end_date`, date): Last day to include. Leave both dates empty to read the last 30 days.
- Bucket unit (`bin_time_unit`, text): What unit the buckets are measured in. One of: `seconds`, `minutes`, `hours`.
- Shortest bucket (`bin_min`, number): Where the buckets start, in the unit above. At least 0.
- Longest bucket (`bin_max`, number): Where the buckets stop, in the unit above. At least 0.
- Bucket size (`bin_size`, number): How wide each bucket is, in the unit above. At least 1.

**Outputs**

- `data` (object)
- `end` (text): Last day read, as YYYYMMDD
- `start` (text): First day read, as YYYYMMDD
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "data": {
    "series": [
      [
        0,
        120408,
        2261,
        6984
      ]
    ],
    "xValues": [
      "0s-60s",
      "60s-120s",
      "120s-180s",
      "180s-240s"
    ]
  },
  "end": "20260904",
  "start": "20260806",
  "status": "success"
}
```

### Get user composition

See how the user base splits across one property - which countries, which platforms, which app versions - with a count for each value in the window.

**Inputs**

- Split by (`user_property`, text, required): Which user property to break the user base down by. Pick a built-in, or type a custom user property as 'gp:your_property'.
- From (`start_date`, date): First day to include. Leave both dates empty to read the last 30 days.
- To (`end_date`, date): Last day to include. Leave both dates empty to read the last 30 days.

**Outputs**

- `data` (object)
- `end` (text): Last day read, as YYYYMMDD
- `start` (text): First day read, as YYYYMMDD
- `status` (text): Status of the action execution ("success" on success).
- `user_property` (text): The property the users were split by

**Example output**

```json
{
  "data": {
    "series": [
      [
        69643,
        47419,
        38087
      ]
    ],
    "seriesLabels": [
      "country"
    ],
    "xValues": [
      "United States",
      "Germany",
      "(none)"
    ]
  },
  "end": "20260904",
  "start": "20260806",
  "status": "success",
  "user_property": "country"
}
```

### List annotations

List the project's chart annotations, optionally narrowed to one category, one chart, or a date range.

**Inputs**

- Category (`category`, text): Only annotations filed under this category name.
- Chart (`chart_id`, text): Only annotations attached to this chart id.
- From (`start_date`, date): First day to include. Give both dates or neither; leave both empty for all of them.
- To (`end_date`, date): Last day to include. Give both dates or neither; leave both empty for all of them.

**Outputs**

- `annotations` (list)
- `count` (number): Annotations returned
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "annotations": [
    {
      "category": {
        "id": 12,
        "name": "Releases"
      },
      "chart_id": null,
      "details": "Shipped to 100% of traffic",
      "end": null,
      "id": 4821,
      "label": "Pricing page redesign",
      "start": "2026-09-01"
    }
  ],
  "count": 1,
  "status": "success"
}
```

### List events

List every event type in the project, with how many times each has been seen and whether it is hidden or deleted. This is where to find the exact spelling the query actions want.

**Inputs**: None.

**Outputs**

- `count` (number): Event types returned
- `events` (list)
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "count": 2,
  "events": [
    {
      "deleted": false,
      "display": "Invoice Paid",
      "flow_hidden": false,
      "hidden": false,
      "non_active": false,
      "totals": 48213,
      "value": "Invoice Paid"
    },
    {
      "deleted": false,
      "display": "Sign Up",
      "flow_hidden": false,
      "hidden": false,
      "non_active": false,
      "totals": 9804,
      "value": "Sign Up"
    }
  ],
  "status": "success"
}
```

### Search users

Find a user in Amplitude by their Amplitude ID, Device ID, User ID, or the start of a User ID. Returns every match with its Amplitude ID. No match is an empty list, not an error.

**Inputs**

- Search for (`user`, text, required): An Amplitude ID, Device ID, User ID, or the first part of a User ID.

**Outputs**

- `count` (number): Users matched
- `match_type` (text): Which kind of id Amplitude matched on
- `matches` (list)
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "count": 1,
  "match_type": "match_user_or_device_id",
  "matches": [
    {
      "amplitude_id": 480851277,
      "user_id": "user-10428"
    }
  ],
  "status": "success"
}
```

### Send event

Record one event in Amplitude for a user or a device, with any event and user properties you want attached, and optionally the revenue it represents. Use this to get whatever a workflow does into your product analytics.

**Inputs**

- Event name (`event_type`, text, required): What happened, as you want it to appear in Amplitude - for example 'Invoice Paid'. A new name creates a new event type.
- User ID (`user_id`, text): Your own id for this person, at least 5 characters - Amplitude rejects shorter ones. Give this or a Device ID.
- Device ID (`device_id`, text): Id of the device the event came from, at least 5 characters. Give this or a User ID.
- Event properties (`event_properties`, object): Details of this occurrence, as name/value pairs.
- User properties (`user_properties`, object): Properties to set on the user at the same time, as name/value pairs.
- When it happened (`time`, date and time): When the event happened. Leave empty to use the moment Amplitude receives it.
- Deduplication key (`insert_id`, text): A unique id for this event. Amplitude ignores a repeat of the same key within 7 days, which makes a retried step safe.
- Platform (`platform`, text): Where the event came from, such as Web or iOS.
- App version (`app_version`, text): Version of your app that produced the event.
- Country (`country`, text): Country to attribute the event to.
- City (`city`, text): City to attribute the event to.
- Revenue (`revenue`, number): Revenue this event represents. Amplitude uses price times quantity when this is empty.
- Price (`price`, number): Price of one unit sold.
- Quantity (`quantity`, number): How many units were sold. At least 0.
- Product ID (`product_id`, text): Identifier of the product involved.
- Revenue type (`revenue_type`, text): How to classify it, such as purchase or refund.

**Outputs**

- `events_ingested` (number): How many events Amplitude stored (1 on success)
- `receipt` (object)
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "events_ingested": 1,
  "receipt": {
    "code": 200,
    "events_ingested": 1,
    "payload_size_bytes": 214,
    "server_upload_time": 1788528000000
  },
  "status": "success"
}
```

### Send events

Record many events at once, up to 2,000 in one call. Each entry is a full event object - the same fields as Send event. Use this to backfill a batch of activity a step has just produced instead of sending them one at a time.

**Inputs**

- Events (`events`, list, required): The events to send. Each needs an 'event_type' and either a 'user_id' or a 'device_id'.

**Outputs**

- `events_ingested` (number): How many events Amplitude stored
- `events_sent` (number): How many events were sent
- `receipt` (object)
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "events_ingested": 2,
  "events_sent": 2,
  "receipt": {
    "code": 200,
    "events_ingested": 2,
    "payload_size_bytes": 402,
    "server_upload_time": 1788528000000
  },
  "status": "success"
}
```

### Set user properties

Update what Amplitude knows about a person without recording an event: set properties, set them only if they are not already there, add to a number, or clear them. Use it to keep plan, role or lifecycle stage current on the user.

**Inputs**

- User ID (`user_id`, text): Your own id for this person, at least 5 characters - Amplitude rejects shorter ones. Give this or a Device ID.
- Device ID (`device_id`, text): Id of the device the event came from, at least 5 characters. Give this or a User ID.
- Set (`set_properties`, object): Properties to set, overwriting whatever is there.
- Set if missing (`set_once_properties`, object): Properties to set only the first time, such as the date someone signed up.
- Add to (`add_properties`, object): Numeric properties to increment by the given amount. Use a negative number to decrement.
- Clear (`unset_properties`, list): Names of properties to remove from the user.

**Outputs**

- `device_id` (text)
- `operations` (list): Which property operations were applied
- `receipt` (object): Amplitude's raw reply
- `status` (text): Status of the action execution ("success" on success).
- `user_id` (text)

**Example output**

```json
{
  "device_id": null,
  "operations": [
    "$set",
    "$setOnce"
  ],
  "receipt": {
    "code": 200,
    "message": "success"
  },
  "status": "success",
  "user_id": "user-10428"
}
```

### Update annotation

Change an existing chart annotation - its label, details, dates, category or chart. Anything left empty stays as it is.

**Inputs**

- Annotation (`annotation_id`, number, required): The annotation's numeric id. Use List annotations to find one.
- Label (`label`, text): New label. Leave empty to keep it as it is.
- Date (`start`, date): New date. Leave empty to keep it as it is.
- End date (`end`, date): New end date. Leave empty to keep it as it is.
- Details (`details`, text): New details. Leave empty to keep them as they are.
- Category (`category`, text): New category name. Leave empty to keep it as it is.
- Chart (`chart_id`, text): New chart id. Leave empty to keep it as it is.

**Outputs**

- `annotation` (object)
- `annotation_id` (number): The annotation's id
- `status` (text): Status of the action execution ("success" on success).

**Example output**

```json
{
  "annotation": {
    "category": {
      "id": 12,
      "name": "Releases"
    },
    "chart_id": null,
    "details": "Shipped to 100% of traffic",
    "end": null,
    "id": 4821,
    "label": "Pricing page redesign",
    "start": "2026-09-01"
  },
  "annotation_id": 4821,
  "status": "success"
}
```