MCPeek

LoginGet Started

Analytics API

Endpoint and payload reference

Complete metrics endpoint list, exact call patterns, and request/response payload contracts.

Scope

This section documents only /v1/metrics/*. Ingest is internal and intentionally excluded here.

Request payload contract

PartRequiredPayloadNotes
Headers (primary)yesx-api-key: mcpeek_xxxExternal integrations should use API key auth.
Headers (secondary/internal)optionalx-session-token + x-organization-idUsed by dashboard server calls.
Query payload (most endpoints)optionalfrom,to,limitApplies to all time-window metrics.
Endpoint-specific query payloadoptionalgranularity | days | threshold | dimensionOnly for endpoints that support those fields.
Request bodynononeAll metrics endpoints are GET and do not take JSON request bodies.

All endpoints

EndpointMethodQuery payloadResponse payloadDescription
/v1/metrics/dauGETfrom,to,limitTimeSeriesResponseDaily active users
/v1/metrics/wauGETfrom,to,limitTimeSeriesResponseWeekly active users
/v1/metrics/mauGETfrom,to,limitTimeSeriesResponseMonthly active users
/v1/metrics/new-usersGETfrom,to,limit,granularityTimeSeriesResponseNew users over time
/v1/metrics/retentionGETfrom,to,limit,daysRetentionResponseRetention cohort response
/v1/metrics/tool-callsGETfrom,to,limitTimeSeriesResponseDaily tool calls
/v1/metrics/daily-sessionsGETfrom,to,limitTimeSeriesResponseDaily sessions
/v1/metrics/session-lengthGETfrom,to,limitTimeSeriesResponseAverage session length
/v1/metrics/tool-calls-per-userGETfrom,to,limitTimeSeriesResponseTool calls per user per day
/v1/metrics/power-usersGETfrom,to,limit,thresholdPowerUsersResponsePower user share
/v1/metrics/users-byGETdimensionUsersByResponseUser distribution by dimension
/v1/metrics/feature-adoptionGETfrom,to,limitFeatureAdoptionResponseFeature adoption distribution

Auth and base request pattern

Headers + query payload

terminal
# Base URL
https://your-domain.com/v1/metrics

# Primary auth header (external)
x-api-key: mcpeek_xxx

# Secondary/internal auth headers (dashboard server calls)
x-session-token: <session_token>
x-organization-id: <org_id>

# Most endpoints are GET with query payload (no JSON request body):
?from=YYYY-MM-DD&to=YYYY-MM-DD&limit=N

Gold-layer endpoint calls

cURL

terminal
# Active users + core usage
curl "https://your-domain.com/v1/metrics/dau?from=2026-02-01&to=2026-02-21&limit=90" \
  -H "x-api-key: $MCPEEK_INGEST_KEY"
curl "https://your-domain.com/v1/metrics/wau?from=2026-02-01&to=2026-02-21&limit=90" \
  -H "x-api-key: $MCPEEK_INGEST_KEY"
curl "https://your-domain.com/v1/metrics/mau?from=2026-02-01&to=2026-02-21&limit=90" \
  -H "x-api-key: $MCPEEK_INGEST_KEY"
curl "https://your-domain.com/v1/metrics/new-users?from=2026-02-01&to=2026-02-21&granularity=day&limit=90" \
  -H "x-api-key: $MCPEEK_INGEST_KEY"
curl "https://your-domain.com/v1/metrics/retention?from=2026-02-01&to=2026-02-21&days=7&limit=90" \
  -H "x-api-key: $MCPEEK_INGEST_KEY"
curl "https://your-domain.com/v1/metrics/tool-calls?from=2026-02-01&to=2026-02-21&limit=90" \
  -H "x-api-key: $MCPEEK_INGEST_KEY"
curl "https://your-domain.com/v1/metrics/daily-sessions?from=2026-02-01&to=2026-02-21&limit=90" \
  -H "x-api-key: $MCPEEK_INGEST_KEY"

Silver-layer endpoint calls

cURL

terminal
# Silver-layer metrics
curl "https://your-domain.com/v1/metrics/session-length?from=2026-02-01&to=2026-02-21&limit=90" \
  -H "x-api-key: $MCPEEK_INGEST_KEY"
curl "https://your-domain.com/v1/metrics/tool-calls-per-user?from=2026-02-01&to=2026-02-21&limit=90" \
  -H "x-api-key: $MCPEEK_INGEST_KEY"
curl "https://your-domain.com/v1/metrics/power-users?from=2026-02-01&to=2026-02-21&threshold=10&limit=90" \
  -H "x-api-key: $MCPEEK_INGEST_KEY"
curl "https://your-domain.com/v1/metrics/users-by?dimension=locale" \
  -H "x-api-key: $MCPEEK_INGEST_KEY"
curl "https://your-domain.com/v1/metrics/feature-adoption?from=2026-02-01&to=2026-02-21&limit=90" \
  -H "x-api-key: $MCPEEK_INGEST_KEY"

Response payloads

TimeSeriesResponse

/dau, /wau, /mau, /new-users, /tool-calls, /daily-sessions, /session-length, /tool-calls-per-user

application/json
{
  "metric": "dau",
  "organizationId": "org_xxx",
  "from": "2026-02-01",
  "to": "2026-02-21",
  "data": [
    { "period": "2026-02-20", "value": 1217 },
    { "period": "2026-02-21", "value": 1248 }
  ]
}

RetentionResponse

/retention

application/json
{
  "metric": "retention",
  "organizationId": "org_xxx",
  "from": "2026-02-01",
  "to": "2026-02-21",
  "days": 7,
  "data": [
    { "period": "2026-02-01", "retained": 101, "cohortSize": 230 }
  ]
}

UsersByResponse

/users-by

application/json
{
  "metric": "users-by",
  "organizationId": "org_xxx",
  "dimension": "locale",
  "data": [
    { "key": "en-US", "count": 921 },
    { "key": "de-DE", "count": 171 }
  ]
}

PowerUsersResponse

/power-users

application/json
{
  "metric": "power-users",
  "organizationId": "org_xxx",
  "from": "2026-02-01",
  "to": "2026-02-21",
  "threshold": 10,
  "totalUsers": 814,
  "powerUsers": 169,
  "percentage": 20.76
}

FeatureAdoptionResponse

/feature-adoption

application/json
{
  "metric": "feature-adoption",
  "organizationId": "org_xxx",
  "from": "2026-02-01",
  "to": "2026-02-21",
  "data": [
    {
      "feature": "requestDisplayMode",
      "sessionsWithFeature": 302,
      "totalSessions": 1048,
      "percentage": 28.82
    }
  ]
}

Rate limits and pagination

  • - Default rate limit: 200 requests per 60s.
  • - No cursor or offset pagination.
  • - Use from, to, and limit to control windows.

Error payloads

StatusErrorWhenPayload
401UnauthorizedMissing/invalid API key or missing auth headers.statusCode,error,message
403ForbiddenSession token is valid but user is not member of requested organization.statusCode,error,message
429Too Many RequestsRate limit exceeded.statusCode,error,message,retryAfter
500Internal Server ErrorUnexpected analytics service failure (including parsing/validation failures in current implementation).statusCode,error,message