Skip to main content

Analytics API

The Analytics API provides programmatic access to product analytics features including event queries, funnels, retention analysis, path analysis, and cohorts.

All endpoints on this page are relative to the base URL: https://api-eu1.joryio.com - see API Overview.

Authentication​

All endpoints require authentication via API key:

Authorization: Bearer YOUR_API_KEY
X-Workspace-Id: YOUR_WORKSPACE_ID

Event Explorer​

List Events​

Get a summary of all tracked events.

GET /analytics/events

Query Parameters:

ParameterTypeDescription
startDatestringStart date (YYYY-MM-DD)
endDatestringEnd date (YYYY-MM-DD)
searchstringFilter by event name
limitnumberMax results (default: 100)

Response:

{
  "events": [
    {
      "eventName": "signup_completed",
      "totalCount": 15420,
      "uniqueUsers": 12350,
      "lastSeen": "2024-01-15T14:30:00Z"
    }
  ],
  "total": 45
}

Get Event Trend​

Get event counts over time.

POST /analytics/events/trend

Request Body:

{
  "eventNames": ["signup_completed", "purchase_completed"],
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "timeGranularity": "day"
}

Response:

[
  {
    "date": "2024-01-01",
    "count": 523,
    "uniqueUsers": 498
  }
]

Get Event Properties​

List properties for a specific event.

GET /analytics/events/:eventName/properties

Response:

[
  {
    "propertyName": "plan_type",
    "valueCount": 4
  },
  {
    "propertyName": "source",
    "valueCount": 12
  }
]

Get Property Breakdown​

Get value distribution for an event property.

POST /analytics/events/property-breakdown

Request Body:

{
  "eventName": "purchase_completed",
  "property": "payment_method",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31"
}

Response:

{
  "total": 5420,
  "values": [
    { "value": "credit_card", "count": 3250, "percentage": 59.96 },
    { "value": "paypal", "count": 1520, "percentage": 28.04 },
    { "value": "bank_transfer", "count": 650, "percentage": 11.99 }
  ]
}

Funnel Analysis​

Create Funnel​

Save a new funnel definition.

POST /analytics/funnels

Request Body:

{
  "name": "Signup to Purchase",
  "steps": [
    {
      "id": "step_1",
      "order": 0,
      "eventName": "signup_completed",
      "filters": []
    },
    {
      "id": "step_2",
      "order": 1,
      "eventName": "onboarding_completed",
      "filters": []
    },
    {
      "id": "step_3",
      "order": 2,
      "eventName": "purchase_completed",
      "filters": []
    }
  ],
  "conversionWindowDays": 7
}

List Funnels​

GET /analytics/funnels

Analyze Funnel​

Run analysis on a saved funnel.

POST /analytics/funnels/:id/analyze

Request Body:

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "breakdown": {
    "type": "event_property",
    "property": "utm_source"
  }
}

Response:

{
  "totalUsers": 10000,
  "overallConversion": 12.5,
  "steps": [
    {
      "id": "step_1",
      "order": 0,
      "eventName": "signup_completed",
      "enteredCount": 10000,
      "conversionRate": 100,
      "dropOffRate": 0
    },
    {
      "id": "step_2",
      "order": 1,
      "eventName": "onboarding_completed",
      "enteredCount": 6500,
      "conversionRate": 65,
      "dropOffRate": 35
    },
    {
      "id": "step_3",
      "order": 2,
      "eventName": "purchase_completed",
      "enteredCount": 1250,
      "conversionRate": 19.23,
      "dropOffRate": 80.77
    }
  ],
  "breakdown": [
    {
      "breakdownValue": "google",
      "overallConversion": 15.2,
      "steps": [...]
    }
  ]
}

Quick Funnel Analysis​

Analyze without saving.

POST /analytics/funnels/quick-analyze

Retention Analysis​

Analyze Retention​

POST /analytics/retention/analyze

Request Body:

{
  "startEvent": "signup_completed",
  "returnEvent": "session_started",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "timeUnit": "week",
  "periods": 8
}

Response:

{
  "timeUnit": "week",
  "cohorts": [
    {
      "cohortDate": "2024-01-01",
      "cohortSize": 1250,
      "periods": [
        { "period": 0, "retainedCount": 1250, "retentionRate": 100 },
        { "period": 1, "retainedCount": 562, "retentionRate": 44.96 },
        { "period": 2, "retainedCount": 375, "retentionRate": 30.0 }
      ]
    }
  ],
  "overallRetention": [100, 45.2, 31.5, 25.8, 22.1, 19.5, 17.8, 16.2]
}

Export Retention​

POST /analytics/retention/export

Returns CSV data.

Path Analysis​

Analyze Paths​

POST /analytics/paths/analyze

Request Body:

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "startEvent": "landing_page_view",
  "direction": "forward",
  "maxSteps": 5,
  "minPathCount": 10,
  "minPathPercent": 0.5,
  "maxBranchesPerStep": 5,
  "excludeEvents": ["heartbeat", "scroll"]
}

minPathCount (absolute users) and minPathPercent (percent of qualifying users, 0-100) set the frequency threshold - a path must clear the larger of the two, so the percentage keeps it portable across workspaces of any size. maxBranchesPerStep (1-50, default 8) caps the flow diagram to the top next events per step so it stays readable at high volume.

Response:

{
  "totalUsers": 25000,
  "totalPaths": 342,
  "paths": [
    {
      "path": ["landing_page_view", "signup_started", "signup_completed"],
      "count": 3250,
      "percentage": 13.0
    }
  ],
  "sankey": {
    "nodes": [
      { "id": "landing_page_view_0", "name": "landing_page_view" }
    ],
    "links": [
      { "source": "landing_page_view_0", "target": "signup_started_1", "value": 5200 }
    ]
  }
}

Cohorts​

Create Cohort​

POST /analytics/cohorts

Request Body:

{
  "name": "Power Users",
  "description": "Users who engage frequently",
  "rules": [
    {
      "type": "event",
      "operator": "did_count",
      "eventName": "session_started",
      "count": 10,
      "timeWindow": { "value": 30, "unit": "day" }
    }
  ]
}

List Cohorts​

GET /analytics/cohorts

Get Cohort​

GET /analytics/cohorts/:id

Update Cohort​

PUT /analytics/cohorts/:id

Delete Cohort​

DELETE /analytics/cohorts/:id

Refresh Cohort Count​

POST /analytics/cohorts/:id/refresh

Create Segment from Cohort​

Link a cohort to a segment for campaign targeting.

POST /analytics/cohorts/:id/create-segment

Request Body:

{
  "segmentName": "Power Users Segment"
}

Dashboards​

Create Dashboard​

POST /analytics/dashboards

Request Body:

{
  "name": "Executive Dashboard",
  "description": "Key metrics overview",
  "widgets": [
    {
      "id": "widget-1",
      "type": "metric",
      "title": "Active Users",
      "config": {
        "eventName": "session_started",
        "metric": "unique_users"
      },
      "layout": { "x": 0, "y": 0, "width": 3, "height": 2 }
    }
  ]
}

List Dashboards​

GET /analytics/dashboards

Get Dashboard​

GET /analytics/dashboards/:id

Update Dashboard​

PUT /analytics/dashboards/:id

Delete Dashboard​

DELETE /analytics/dashboards/:id

Real-time Analytics​

Get Active Users​

GET /analytics/realtime/active-users

Response:

{
  "count": 1523,
  "trend": 5.2
}

Live Events Stream (SSE)​

GET /analytics/realtime/events/stream

Returns a Server-Sent Events stream of live events.

Error Responses​

All endpoints return standard error responses:

{
  "statusCode": 400,
  "message": "Invalid date range",
  "error": "Bad Request"
}
Status CodeDescription
400Bad request / validation error
401Unauthorized
403Forbidden
404Resource not found
500Internal server error