Skip to content

mixpanel_bookmark (Resource)

Manages a Mixpanel saved report (bookmark) (mixpanel_bookmark) — a report definition (insights, funnels, retention, flows, or other types) that can live standalone or as a cell on a board. See mixpanel_dashboard for boards.

Example Usage

# Board report bookmarks (type insights/retention/funnels/flows) require a
# dashboard: the provider creates them through the dashboards content API so
# the report actually appears on the board.
resource "mixpanel_dashboard" "board" {
  title = "Product KPIs"
}

resource "mixpanel_bookmark" "all_events" {
  name         = "All events over time"
  type         = "insights"
  dashboard_id = mixpanel_dashboard.board.id

  params = jsonencode({
    sections = {
      show = [{
        dataset      = "$mixpanel"
        value        = { name = "$all_events", resourceType = "events" }
        resourceType = "events"
        search       = ""
        math         = "total"
      }]
    }
    displayOptions = { chartType = "line" }
  })
}

Board reports: create/delete go through the board

Bookmarks whose type is insights, retention, funnels, or flows are board reports (the report types Mixpanel allows on a board): they only exist as a cell on a board. For these types (live-verified against the Mixpanel app API):

  • dashboard_id is required (enforced at plan time). The provider creates the report through the dashboards content API (PATCH /dashboards/{id} with a content.action = "create" body), which atomically creates the bookmark and its board layout row/cell. The standalone POST /bookmarks endpoint is not used for board types because it silently drops dashboard_id — the report would never appear on any board.
  • Deletion also goes through the dashboards content API (content.action = "delete"), which soft-deletes the bookmark and removes its layout cell. (The standalone DELETE /bookmarks/{id} returns HTTP 500 for board types.) If the board itself is already gone, the delete is treated as complete.
  • Changing dashboard_id replaces the bookmark. The API cannot move a report between boards in place: a standalone PATCH updates the bookmark's dashboard_id but leaves the layout cell on the old board (a half-move), so the provider marks dashboard_id as requiring replacement.
  • Transient HTTP 409 conflicts on the dashboards content path are retried (3 attempts with backoff).

Name/description/params updates still use the standalone PATCH /bookmarks/{id} and work in place.

params must be a valid report definition for the bookmark's type — for insights, at least one sections.show clause and a displayOptions.chartType (the content API rejects invalid params with 400 InvalidParams).

params drift semantics

The server normalizes params in the content-create echo (e.g. insights events are rewritten into behavior clauses), but GET /bookmarks/{id} round-trips the original params you sent, so refresh and drift detection for params work normally: out-of-band edits to a report's definition are detected on refresh, and the server echo never causes spurious diffs.

Schema

Optional

  • bookmark_id (Number)
  • bookmark_url_slug (String)
  • dashboard_id (String) The board the report lives on. Required for board report types (insights, retention, funnels, flows). Changing it forces a replacement (the API cannot move a report between boards in place).
  • deleted (String)
  • description (String)
  • global_access_type (String)
  • icon (String)
  • is_modification_restricted (String)
  • is_visibility_restricted (String)
  • metadata (String)
  • name (String)
  • params (String)
  • prev_bookmark_url_slug (String)
  • share_with_project (Boolean) Whether to share this entity with the whole project after creation. Entities created by a service account are otherwise visible only to that service account. Defaults to true. See the Entity sharing guide.
  • type (String)
  • v (String)

Read-Only

  • allow_staff_override (Boolean)
  • can_share (Boolean)
  • can_update_basic (Boolean)
  • can_view (Boolean)
  • created (String)
  • creator (String)
  • creator_email (String)
  • creator_id (Number)
  • creator_name (String)
  • generation_type (String)
  • id (Number) The ID of this resource.
  • include_in_dashboard (Boolean)
  • is_default (Boolean)
  • is_superadmin (Boolean)
  • last_modified_by_email (String)
  • last_modified_by_id (Number)
  • last_modified_by_name (String)
  • modified (String)
  • original_type (String)
  • project_id (Number)
  • total_view_count (Number)
  • unique_view_count (Number)
  • workspace_id (Number)

Plan-time validation of params

Bookmark params are validated at terraform plan time against the known-corrupting shapes:

  • when type is "funnels" and the params carry a legacy steps array, it must have between 1 and 100 steps (100 is the server-side funnel-step limit (100 steps) — a bigger funnel saves but every query on it fails);
  • multi-metric params (params.sections.show[]) apply the behavior and measurement rules from the mixpanel_behavior / mixpanel_metric docs (funnels need at least 2 named steps; property-aggregating math needs a non-null object property; funnelOrder is "loose" or "any").

Import

Bookmarks can be imported using the composite PROJECT_ID:ID format:

import {
  to = mixpanel_bookmark.all_events
  id = "1234567:890"
}

terraform import mixpanel_bookmark.all_events 1234567:890