KosmoKrator

analytics

Mixpanel Analytics Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Mixpanel Analytics KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.mixpanel.*. Use lua_read_doc("integrations.mixpanel") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Mixpanel Analytics workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.mixpanel.get_cohort({id = "example_id"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("mixpanel"))' --json
kosmo integrations:lua --eval 'print(docs.read("mixpanel.get_cohort"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local mixpanel = app.integrations.mixpanel
local result = mixpanel.get_cohort({id = "example_id"})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.mixpanel, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.mixpanel.default.* or app.integrations.mixpanel.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Mixpanel Analytics, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Mixpanel Analytics — Lua API Reference

list_events

List events from Mixpanel, optionally filtered by type, unit, or date range.

Parameters

NameTypeRequiredDescription
typestringnoEvent type: "general" or "unique" (default: "general")
unitstringnoTime unit: "hour", "day", "week", "month" (default: "day")
fromstringnoStart date in YYYY-MM-DD format
tostringnoEnd date in YYYY-MM-DD format
limitintegernoMaximum number of events to return (default: 100)

Examples

-- Get recent events
local result = app.integrations.mixpanel.list_events({
  limit = 50
})

for name, data in pairs(result.data or {}) do
  print("Event: " .. name)
end
-- Get events in a date range
local result = app.integrations.mixpanel.list_events({
  from = "2025-01-01",
  to = "2025-01-31",
  unit = "day",
  limit = 100
})

get_event

Retrieve analytics data for a specific event by name.

Parameters

NameTypeRequiredDescription
namestringyesThe event name to retrieve data for
typestringnoEvent type: "general" or "unique" (default: "general")
unitstringnoTime unit: "hour", "day", "week", "month" (default: "day")
fromstringnoStart date in YYYY-MM-DD format
tostringnoEnd date in YYYY-MM-DD format

Example

local result = app.integrations.mixpanel.get_event({
  name = "Page View",
  from = "2025-01-01",
  to = "2025-01-31"
})

for date, count in pairs(result.data or {}) do
  print("Date: " .. date .. " — Count: " .. tostring(count))
end

list_funnels

List all funnels configured in the Mixpanel project.

Parameters

None.

Example

local result = app.integrations.mixpanel.list_funnels({})

for _, funnel in ipairs(result.data or {}) do
  print("Funnel: " .. funnel.name .. " (ID: " .. tostring(funnel.id) .. ")")
end

get_funnel

Retrieve detailed conversion data for a Mixpanel funnel by its ID.

Parameters

NameTypeRequiredDescription
idstringyesThe Mixpanel funnel ID

Example

local result = app.integrations.mixpanel.get_funnel({
  id = "12345"
})

print("Funnel: " .. (result.data.name or "unknown"))
for _, step in ipairs(result.data.steps or {}) do
  print("  Step: " .. step.event .. " — Conversion: " .. tostring(step.conversion_ratio))
end

list_cohorts

List all behavioral cohorts in the Mixpanel project.

Parameters

None.

Example

local result = app.integrations.mixpanel.list_cohorts({})

for _, cohort in ipairs(result.data or {}) do
  print("Cohort: " .. cohort.name .. " (ID: " .. tostring(cohort.id) .. ")")
end

get_cohort

Retrieve detailed information for a Mixpanel cohort by its ID.

Parameters

NameTypeRequiredDescription
idstringyesThe Mixpanel cohort ID

Example

local result = app.integrations.mixpanel.get_cohort({
  id = "67890"
})

print("Cohort: " .. (result.data.name or "unknown"))
print("Count: " .. tostring(result.data.count or 0))

get_current_user

Get the currently authenticated Mixpanel user (caller identity).

Parameters

None.

Example

local result = app.integrations.mixpanel.get_current_user({})

print("Logged in as: " .. (result.name or result.email or "unknown"))
print("Role: " .. (result.role or "N/A"))

Multi-Account Usage

If you have multiple Mixpanel accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.mixpanel.list_events({limit = 50})

-- Explicit default (portable across setups)
app.integrations.mixpanel.default.list_events({limit = 50})

-- Named accounts
app.integrations.mixpanel.production.list_events({limit = 50})
app.integrations.mixpanel.staging.list_events({limit = 50})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Mixpanel Analytics — Lua API Reference

## list_events

List events from Mixpanel, optionally filtered by type, unit, or date range.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `type` | string | no | Event type: `"general"` or `"unique"` (default: `"general"`) |
| `unit` | string | no | Time unit: `"hour"`, `"day"`, `"week"`, `"month"` (default: `"day"`) |
| `from` | string | no | Start date in YYYY-MM-DD format |
| `to` | string | no | End date in YYYY-MM-DD format |
| `limit` | integer | no | Maximum number of events to return (default: 100) |

### Examples

```lua
-- Get recent events
local result = app.integrations.mixpanel.list_events({
  limit = 50
})

for name, data in pairs(result.data or {}) do
  print("Event: " .. name)
end
```

```lua
-- Get events in a date range
local result = app.integrations.mixpanel.list_events({
  from = "2025-01-01",
  to = "2025-01-31",
  unit = "day",
  limit = 100
})
```

---

## get_event

Retrieve analytics data for a specific event by name.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | yes | The event name to retrieve data for |
| `type` | string | no | Event type: `"general"` or `"unique"` (default: `"general"`) |
| `unit` | string | no | Time unit: `"hour"`, `"day"`, `"week"`, `"month"` (default: `"day"`) |
| `from` | string | no | Start date in YYYY-MM-DD format |
| `to` | string | no | End date in YYYY-MM-DD format |

### Example

```lua
local result = app.integrations.mixpanel.get_event({
  name = "Page View",
  from = "2025-01-01",
  to = "2025-01-31"
})

for date, count in pairs(result.data or {}) do
  print("Date: " .. date .. " — Count: " .. tostring(count))
end
```

---

## list_funnels

List all funnels configured in the Mixpanel project.

### Parameters

None.

### Example

```lua
local result = app.integrations.mixpanel.list_funnels({})

for _, funnel in ipairs(result.data or {}) do
  print("Funnel: " .. funnel.name .. " (ID: " .. tostring(funnel.id) .. ")")
end
```

---

## get_funnel

Retrieve detailed conversion data for a Mixpanel funnel by its ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The Mixpanel funnel ID |

### Example

```lua
local result = app.integrations.mixpanel.get_funnel({
  id = "12345"
})

print("Funnel: " .. (result.data.name or "unknown"))
for _, step in ipairs(result.data.steps or {}) do
  print("  Step: " .. step.event .. " — Conversion: " .. tostring(step.conversion_ratio))
end
```

---

## list_cohorts

List all behavioral cohorts in the Mixpanel project.

### Parameters

None.

### Example

```lua
local result = app.integrations.mixpanel.list_cohorts({})

for _, cohort in ipairs(result.data or {}) do
  print("Cohort: " .. cohort.name .. " (ID: " .. tostring(cohort.id) .. ")")
end
```

---

## get_cohort

Retrieve detailed information for a Mixpanel cohort by its ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The Mixpanel cohort ID |

### Example

```lua
local result = app.integrations.mixpanel.get_cohort({
  id = "67890"
})

print("Cohort: " .. (result.data.name or "unknown"))
print("Count: " .. tostring(result.data.count or 0))
```

---

## get_current_user

Get the currently authenticated Mixpanel user (caller identity).

### Parameters

None.

### Example

```lua
local result = app.integrations.mixpanel.get_current_user({})

print("Logged in as: " .. (result.name or result.email or "unknown"))
print("Role: " .. (result.role or "N/A"))
```

---

## Multi-Account Usage

If you have multiple Mixpanel accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.mixpanel.list_events({limit = 50})

-- Explicit default (portable across setups)
app.integrations.mixpanel.default.list_events({limit = 50})

-- Named accounts
app.integrations.mixpanel.production.list_events({limit = 50})
app.integrations.mixpanel.staging.list_events({limit = 50})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.mixpanel.get_cohort({id = "example_id"})
print(result)

Functions

get_cohort Read

Retrieve detailed information for a Mixpanel cohort by its ID. Returns cohort membership data and behavioral criteria.

Lua path
app.integrations.mixpanel.get_cohort
Full name
mixpanel.mixpanel_get_cohort
ParameterTypeRequiredDescription
id string yes The Mixpanel cohort ID.
get_current_user Read

Get the currently authenticated Mixpanel user. Returns account details for the API key owner — useful for verifying credentials and checking permissions.

Lua path
app.integrations.mixpanel.get_current_user
Full name
mixpanel.mixpanel_get_current_user
ParameterTypeRequiredDescription
No parameters.
get_event Read

Retrieve analytics data for a specific Mixpanel event by name. Returns event counts and breakdowns over time.

Lua path
app.integrations.mixpanel.get_event
Full name
mixpanel.mixpanel_get_event
ParameterTypeRequiredDescription
name string yes The event name to retrieve data for.
type string no Event type: "general" or "unique" (default: "general").
unit string no Time unit: "hour", "day", "week", "month" (default: "day").
from string no Start date in YYYY-MM-DD format.
to string no End date in YYYY-MM-DD format.
get_funnel Read

Retrieve detailed conversion data for a Mixpanel funnel by its ID. Returns step-by-step conversion rates and drop-off analytics.

Lua path
app.integrations.mixpanel.get_funnel
Full name
mixpanel.mixpanel_get_funnel
ParameterTypeRequiredDescription
id string yes The Mixpanel funnel ID.
list_cohorts Read

List all behavioral cohorts in the Mixpanel project. Returns cohort names, IDs, and sizes.

Lua path
app.integrations.mixpanel.list_cohorts
Full name
mixpanel.mixpanel_list_cohorts
ParameterTypeRequiredDescription
No parameters.
list_events Read

List events from Mixpanel Analytics. Optionally filter by event type, time unit, or date range. Returns the most recent events matching the criteria.

Lua path
app.integrations.mixpanel.list_events
Full name
mixpanel.mixpanel_list_events
ParameterTypeRequiredDescription
type string no Event type: "general" or "unique" (default: "general").
unit string no Time unit: "hour", "day", "week", "month" (default: "day").
from string no Start date in YYYY-MM-DD format.
to string no End date in YYYY-MM-DD format.
limit integer no Maximum number of events to return (default: 100).
list_funnels Read

List all funnels configured in the Mixpanel project. Returns funnel names, IDs, and basic configuration.

Lua path
app.integrations.mixpanel.list_funnels
Full name
mixpanel.mixpanel_list_funnels
ParameterTypeRequiredDescription
No parameters.