# Get Retention Analysis — Amplitude

> Compute retention (return rate) between a start event and a return event over a date range from the Amplitude Dashboard REST API. Example: call with startEvent={"event_type":"_new"}, returnEvent={"event_type":"_active"}…

- Key: `amplitude-get-retention-analysis`
- Type: Action (Read-only)
- Version: 0.0.2
- App: Amplitude (`amplitude`) — https://pipedream.com/apps/amplitude.md
- This page (HTML): https://pipedream.com/apps/amplitude/actions/get-retention-analysis
- Hints: read-only · open-world
- Source: https://github.com/PipedreamHQ/pipedream/blob/master/components/amplitude/actions/get-retention-analysis/get-retention-analysis.mjs

## Description

Compute retention (return rate) between a start event and a return event over a date range from the Amplitude Dashboard REST API. Example: call with `startEvent={"event_type":"_new"}`, `returnEvent={"event_type":"_active"}`, `startDate="20240706"`, `endDate="20240805"` -> returns `{data: {series: [[...retention counts per interval...]], seriesLabels: [...]}}`. [See the documentation](https://amplitude.com/docs/apis/analytics/dashboard-rest#retention-analysis).

## Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `startEvent` | `string` | Yes | JSON-encoded start event definition (the se param). Use a real event name, or Amplitude's built-in _new (new user) event. Example: {"event_type":"_new"}. Do NOT use the literal string "Any Active Event" — that's Amplitude UI label text, not a valid event_type value, and returns a 400. |
| `returnEvent` | `string` | Yes | JSON-encoded return event definition (the re param). Use a real event name, or Amplitude's built-in _active (active user) event. Example: {"event_type":"_active"}. Do NOT use the literal string "Any Active Event" — that's Amplitude UI label text, not a valid event_type value, and returns a 400. |
| `startDate` | `string` | Yes | Start date, inclusive, in YYYYMMDD format (the start param). Example: 20240706. |
| `endDate` | `string` | Yes | End date, inclusive, in YYYYMMDD format (the end param). Example: 20240805. |
| `retentionMode` | `string` | No | Retention calculation mode (the rm param). One of bracket, rolling, nday. Defaults to nday. (Amplitude's own docs say n-day with a hyphen — that value is rejected by the live API with a 400; the working value is nday, no hyphen, confirmed directly against the API.) rolling returns an unbounded, much larger response — prefer nday unless you specifically need rolling retention, and if using rolling over a long date range, raise interval (e.g. to 7 or 30) to keep the response size manageable. |
| `brackets` | `string` | No | Bracket day-ranges as a JSON-encoded array of [start, end] integer pairs, required only when Retention Mode is bracket (the rb param). Each pair is a day offset range (start must be ≤ end; Amplitude returns a 500 for a reversed range). Example: [[0,4]] for a single 0-4 day bracket, or [[0,4],[5,9]] for two brackets. |
| `interval` | `integer` | No | Time interval (the i param). One of 1 (daily), 7 (weekly), 30 (monthly). Defaults to 1 (daily), but daily granularity over a date range wider than ~2 weeks produces a very large response (one retention curve per day in range) that can exceed the MCP output limit. For any date range longer than 2 weeks, pass 7 (weekly) or 30 (monthly) instead of relying on the default. |
| `segmentDefinitions` | `string` | No | JSON-encoded array of segment definitions (the s param). Example: [{"prop":"country","op":"is","values":["US"]}]. |
| `groupBy` | `string` | No | A single property name to group results by (the g param). Retention supports at most one group-by. |
| `limit` | `integer` | No | Maximum number of grouped values to return (the limit param). Min 1, max 1000. Defaults to 100. Amplitude has no cursor for this endpoint — values beyond this cap are silently dropped by the API, not just this tool. If more than limit distinct group-by values may exist, raise this toward 1000 or narrow with Segment Definitions/Group By. |

## Run it

**MCP**

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const accessToken = await pd.rawAccessToken

const transport = new StreamableHTTPClientTransport(
  new URL("https://remote.mcp.pipedream.net/v3"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "x-pd-project-id": process.env.PIPEDREAM_PROJECT_ID!,
        "x-pd-environment": "production",
        "x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
        "x-pd-app-slug": "amplitude",
      },
    },
  },
)

const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)

const { tools } = await mcp.listTools()

// listTools() hands your model this tool's input schema, so it can
// fill the arguments itself:
const result = await mcp.callTool({
  name: "amplitude-get-retention-analysis",
  arguments: {
    startEvent: "Start Event",
    returnEvent: "Return Event",
  },
})
```

**TypeScript**

```ts
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "amplitude-get-retention-analysis",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    amplitude: { authProvisionId: "apn_xxxxxxx" },
    startEvent: "Start Event",
    returnEvent: "Return Event",
  },
})

console.log(result)
```

**cURL**

```bash
curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
  -H "Content-Type: application/json" \
  -H "X-PD-Environment: production" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "external_user_id": "{external_user_id}",
    "id": "amplitude-get-retention-analysis",
    "configured_props": {
      "amplitude": { "authProvisionId": "apn_xxxxxxx" },
      "startEvent": "Start Event",
      "returnEvent": "Return Event"
    }
  }'
```

---

- App: https://pipedream.com/apps/amplitude.md · All apps: https://pipedream.com/apps