> ## Documentation Index
> Fetch the complete documentation index at: https://developers.autoplay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API (optional)

> The optional REST fallback for pulling a user's recent in-app activity — for agents that can't speak MCP. Same data as the MCP tool.

<Note>
  🔌 **Most agents should use the [MCP server](/mcp/server) instead** — it's the recommended way to read live activity. This page is the **optional REST fallback** for agents that can't speak MCP. It returns the **same data** via plain HTTP.
</Note>

The REST endpoint hands any AI agent a user's recent in-app footsteps — pages viewed, buttons clicked, forms submitted — at the exact moment it needs context to answer.

Think of it as a **lookup desk**: an agent walks up with a `product_id` and a `user_id`, and the connector hands back the last few things that user did.

## 🌐 The endpoint

```
GET https://mcp.autoplay.ai/users/{product_id}/{user_id}/live-activity
```

| Part           | Meaning                                                                                                                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{product_id}` | Your Autoplay product id — the same `YOUR_PRODUCT_ID` you registered in the [Quickstart](/quickstart).                                                                                                                    |
| `{user_id}`    | The **stable** user identifier your activity source stamps events with (e.g. the id you pass to `posthog.identify(...)`; the Amplitude `user_id`; …). This match is the linchpin; see **[Identity](/activity/identity)**. |
| `?limit=`      | Optional. Max recent actions to return. Omitted or `<= 0` falls back to the configured cap (50).                                                                                                                          |

**Auth** — `Authorization: Bearer YOUR_MCP_KEY` (the `mcp_key` from your Quickstart product registration).

* **401** — token missing or invalid.
* **403** — the token is valid but its `external_id` doesn't match the `{product_id}` in the URL (a key for product A can't read product B).

## 📦 The response

The envelope, with `actions` ordered **oldest → newest**:

```json theme={null}
{
  "product_id": "YOUR_PRODUCT_ID",
  "user_id": "user_12345",
  "count": 3,
  "as_of": 1736940750.881,
  "actions": [
    {
      "type": "pageview",
      "title": "Page Load: Dashboard",
      "description": "User landed on the dashboard page",
      "timestamp_start": 1736940685.103,
      "timestamp_end": 1736940691.250,
      "raw_url": "https://app.example.com/dashboard",
      "canonical_url": "https://app.example.com/dashboard",
      "index": 0
    },
    {
      "type": "click",
      "title": "Click Export Csv",
      "description": "User clicked the Export Csv button on the dashboard page",
      "timestamp_start": 1736940691.250,
      "timestamp_end": 1736940705.610,
      "raw_url": "https://app.example.com/orders/12345",
      "canonical_url": "https://app.example.com/orders/:id",
      "index": 1
    },
    {
      "type": "submit",
      "title": "Submit Payment Form",
      "description": "User submitted the Payment form on the checkout page",
      "timestamp_start": 1736940705.610,
      "timestamp_end": 1736940705.610,
      "raw_url": "https://app.example.com/checkout",
      "canonical_url": "https://app.example.com/checkout",
      "index": 2
    }
  ]
}
```

Each action carries `type`, `title`, `description`, `timestamp_start`, `timestamp_end`, `raw_url`, `canonical_url`, and `index`. The `user_id` lives on the envelope, not inside each action.

<Tip>
  **Test it from your terminal** before wiring any agent. Use a real product id, a `user_id` you've actually identified, and your `mcp_key`:

  ```bash theme={null}
  curl "https://mcp.autoplay.ai/users/YOUR_PRODUCT_ID/user_12345/live-activity?limit=10" \
    -H "Authorization: Bearer YOUR_MCP_KEY"
  ```

  A `200` with a populated `actions` array means the desk is open and the user has footsteps on file.
</Tip>

## ⏳ Before activity appears

This surface only returns something once the connector has **recorded** activity for that user — your activity source must be wired up and the user must have generated events.

**With PostHog** (the source used in the Quickstart): complete **[Quickstart](/quickstart) Steps 1–3** — the snippet, `posthog.identify(...)`, product registration, and the ingest webhook. Other sources (e.g. Amplitude) follow the same idea through their own ingestion path.

<Warning>
  **Identifying a user alone stores nothing.** With PostHog, activity is built only from **`$pageview`** and **`$autocapture`** events (page loads, clicks, form submits) — a user who has identified but not yet browsed returns an **empty** `actions` array. Other sources capture their own equivalent events. Make sure capture is enabled and the user has actually navigated/clicked before expecting results.
</Warning>

<Note>
  **Retention** — this is short-lived "live" memory, not an archive:

  * **4-hour TTL** (`ACTIVITY_TTL_S` = `14400`) — older activity expires.
  * **50 actions max** per user (`ACTIVITY_MAX_EVENTS` = `50`) — older ones are trimmed.
</Note>