AI Productivity Insights

Run AI-powered analysis on your productivity data. The insights engine analyzes bit completion patterns across your chains and chainies to detect trends, flag anomalies, suggest optimizations, and forecast progress.

Endpoints

Method	Path	Description	Auth	Rate Limit
POST	/ai/productivity-insights/analyze	Run an analysis	JWT + Entitlement	20/min
GET	/ai/productivity-insights	List past insights	JWT + Entitlement	60/min

---

POST /ai/productivity-insights/analyze

Description

Run AI analysis on productivity patterns within a date range.

Authentication: JWT Bearer token + active AI entitlement required. Rate limit: 20/min

Request

• Headers: Authorization: Bearer <token>, Content-Type: application/json

Request Body

Field	Type	Required	Description
scope	string	Yes	Analysis scope: account, chainy, or chain
scopeId	string (uuid)	No	Target ID when scope is chainy or chain
insightType	string	Yes	One of: trend, anomaly, optimization, forecast
from	string (ISO 8601)	No	Start date (defaults to 30 days ago)
to	string (ISO 8601)	No	End date (defaults to now)

Insight Types

Type	What It Does
trend	Splits the date range in half, compares average daily completions, and determines if you are improving, declining, or stable
anomaly	Detects days with unusually high activity (spikes) or unexpected gaps
optimization	Generates actionable suggestions based on streak patterns, chain count, and daily pace
forecast	Projects completion counts for the next 7 and 30 days based on your current pace

Response

Response Example (Trend)

{
  "data": {
    "id": "cm5insight01",
    "scope": "account",
    "scopeId": null,
    "insightType": "trend",
    "content": {
      "direction": "improving",
      "avgDailyCompletions": 3.2,
      "firstHalfAvg": 2.1,
      "secondHalfAvg": 4.3,
      "activeChains": 4,
      "totalCompletions": 96
    },
    "runId": null,
    "createdAt": "2026-03-17T14:00:00.000Z"
  }
}

Response Example (Anomaly)

{
  "data": {
    "id": "cm5insight02",
    "scope": "account",
    "scopeId": null,
    "insightType": "anomaly",
    "content": {
      "avgDailyCompletions": 3.2,
      "anomalyCount": 3,
      "anomalies": [
        { "date": "2026-03-01", "count": 12, "type": "spike" },
        { "date": "2026-03-05", "count": 0, "type": "gap" },
        { "date": "2026-03-10", "count": 11, "type": "spike" }
      ]
    },
    "runId": null,
    "createdAt": "2026-03-17T14:00:00.000Z"
  }
}

Response Example (Optimization)

{
  "data": {
    "id": "cm5insight03",
    "scope": "chainy",
    "scopeId": "cm5abc123",
    "insightType": "optimization",
    "content": {
      "currentAvgStreak": 2.5,
      "activeChains": 7,
      "suggestions": [
        "Focus on building consistent streaks before adding new chains.",
        "Consider consolidating chains -- too many parallel goals can reduce focus."
      ]
    },
    "runId": null,
    "createdAt": "2026-03-17T14:00:00.000Z"
  }
}

Response Example (Forecast)

{
  "data": {
    "id": "cm5insight04",
    "scope": "account",
    "scopeId": null,
    "insightType": "forecast",
    "content": {
      "projectedCompletions7d": 22,
      "projectedCompletions30d": 96,
      "currentPace": 3.2,
      "requiredPaceForTarget": null
    },
    "runId": null,
    "createdAt": "2026-03-17T14:00:00.000Z"
  }
}

Response Fields

Field	Type	Description
id	string	Insight UUID
scope	string	Analysis scope (account, chainy, chain)
scopeId	string | null	Target ID (null for account scope)
insightType	string	The insight type
content	object	Analysis results (structure varies by insight type)
runId	string | null	Associated AI run ID (if generated by LLM)
createdAt	string	ISO 8601 timestamp

Code Examples

cURL

curl -X POST https://api.chainabit.com/api/v1/ai/productivity-insights/analyze \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "account",
    "insightType": "trend",
    "from": "2026-02-15T00:00:00.000Z",
    "to": "2026-03-17T00:00:00.000Z"
  }'

JavaScript

const res = await fetch(`${BASE_URL}/ai/productivity-insights/analyze`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    scope: "account",
    insightType: "trend",
    from: "2026-02-15T00:00:00.000Z",
    to: "2026-03-17T00:00:00.000Z",
  }),
});
const { data } = await res.json();

Python

import requests

res = requests.post(
    f"{BASE_URL}/ai/productivity-insights/analyze",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "scope": "account",
        "insightType": "trend",
        "from": "2026-02-15T00:00:00.000Z",
        "to": "2026-03-17T00:00:00.000Z",
    },
)
data = res.json()["data"]

---

GET /ai/productivity-insights

Description

List your past productivity insights, ordered by most recent first. Returns up to 20 results.

Authentication: JWT Bearer token + active AI entitlement required. Rate limit: 60/min

Request

• Headers: Authorization: Bearer <token>

Response

Response Example

{
  "data": [
    {
      "id": "cm5insight01",
      "scope": "account",
      "scopeId": null,
      "insightType": "trend",
      "content": {
        "direction": "improving",
        "avgDailyCompletions": 3.2,
        "firstHalfAvg": 2.1,
        "secondHalfAvg": 4.3,
        "activeChains": 4,
        "totalCompletions": 96
      },
      "runId": null,
      "createdAt": "2026-03-17T14:00:00.000Z"
    },
    {
      "id": "cm5insight02",
      "scope": "chainy",
      "scopeId": "cm5abc123",
      "insightType": "optimization",
      "content": {
        "currentAvgStreak": 2.5,
        "activeChains": 7,
        "suggestions": [
          "Focus on building consistent streaks before adding new chains."
        ]
      },
      "runId": null,
      "createdAt": "2026-03-16T10:00:00.000Z"
    }
  ]
}

Code Examples

cURL

curl https://api.chainabit.com/api/v1/ai/productivity-insights \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const res = await fetch(`${BASE_URL}/ai/productivity-insights`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data } = await res.json();

Python

import requests

res = requests.get(
    f"{BASE_URL}/ai/productivity-insights",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]