Skip to main content

​
Get Stats

Retrieve journaling statistics including streak data, mood distribution, and engagement metrics. 
curl http://127.0.0.1:5000/api/stats

{
  "streak": {
    "current_streak": 7,
    "longest_streak": 14,
    "total_entries": 45,
    "this_week": 5,
    "this_month": 18,
    "last_entry_date": "2024-03-15"
  },
  "encouragement": "Amazing 7-day streak! Consistency is your superpower.",
  "mood_distribution": {
    "very_positive": 12,
    "positive": 18,
    "neutral": 10,
    "negative": 4,
    "very_negative": 1
  },
  "total_words": 12847,
  "average_words": 285,
  "week_chain": [
    {"date": "2024-03-09", "day": "S", "has_entry": false, "is_today": false},
    {"date": "2024-03-10", "day": "M", "has_entry": true, "is_today": false},
    {"date": "2024-03-11", "day": "T", "has_entry": true, "is_today": false},
    {"date": "2024-03-12", "day": "W", "has_entry": true, "is_today": false},
    {"date": "2024-03-13", "day": "T", "has_entry": true, "is_today": false},
    {"date": "2024-03-14", "day": "F", "has_entry": true, "is_today": false},
    {"date": "2024-03-15", "day": "S", "has_entry": true, "is_today": true}
  ],
  "journaled_today": true,
  "hours_remaining": 8.5,
  "streak_status": "safe",
  "badges": [
    {"days": 7, "achieved": true, "label": "7 Days"},
    {"days": 14, "achieved": false, "label": "14 Days"},
    {"days": 30, "achieved": false, "label": "30 Days"},
    {"days": 60, "achieved": false, "label": "60 Days"},
    {"days": 100, "achieved": false, "label": "100 Days"},
    {"days": 365, "achieved": false, "label": "365 Days"}
  ],
  "next_milestone": {
    "days": 14,
    "remaining": 7,
    "progress": 50
  },
  "weekly_goal": {
    "target": 5,
    "current": 5,
    "progress": 100
  }
}

​
Response Fields

​
Streak Data

​
streak
object
required
Detailed streak and engagement statistics

​
Encouragement

​
encouragement
string
Personalized message based on streak length
Examples:
  • “Start your journaling journey today. Every story begins with one page.”
  • “Great start! One day at a time builds lasting habits.”
  • “7 days strong! You’re building something meaningful.”
  • “Amazing 30-day streak! Consistency is your superpower.”
  • “Incredible 100 days! Your dedication to self-reflection inspires.”
  • “Legendary 365-day streak! You’ve mastered the art of daily reflection.”

​
Mood Distribution

​
mood_distribution
object
required
Count of entries for each mood category

​
Writing Stats

​
total_words
number
Sum of word counts across all entries
​
average_words
number
Average words per entry (rounded)

​
Week Chain

​
week_chain
array
Visual representation of last 7 days

​
Today’s Status

​
journaled_today
boolean
Whether you’ve journaled today
​
hours_remaining
number
Hours remaining in the day (rounded to 1 decimal)
​
streak_status
string
Current streak status
Possible values:
  • safe - Already journaled today
  • reminder - Haven’t journaled, 6-12 hours left
  • at_risk - Haven’t journaled, < 6 hours left
  • start - No current streak

​
Badges

​
badges
array
Milestone badges for streak achievements
Milestones: 7, 14, 30, 60, 100, 365 days

​
Next Milestone

​
next_milestone
object | null
Information about the next unachieved milestone
Returns null if all milestones achieved.

​
Weekly Goal

​
weekly_goal
object
Progress toward weekly journaling goal (default: 5 days)

​
Streak Calculation

The streak algorithm:
  1. Current streak: Consecutive days with entries, ending today or yesterday
    • If you journal today, the streak continues
    • If you journal yesterday but not today, the streak is still active (grace period)
    • If you miss both today and yesterday, the streak resets to 0
  2. Longest streak: Maximum consecutive days ever achieved
  3. Counts: Simple counts over specified time periods

​
Use Cases

​
Display Dashboard

Use this endpoint to build a stats dashboard: 
const stats = await fetch('http://127.0.0.1:5000/api/stats').then(r => r.json());

// Show streak
console.log(`${stats.streak.current_streak} day streak!`);

// Show encouragement
console.log(stats.encouragement);

// Display week chain
stats.week_chain.forEach(day => {
  console.log(`${day.day}: ${day.has_entry ? '✓' : '○'}`);
});

// Show badges
stats.badges.forEach(badge => {
  if (badge.achieved) {
    console.log(`🏆 ${badge.label}`);
  }
});

​
Gamification

Use badges and milestones for motivation: 
if (stats.next_milestone) {
  console.log(
    `${stats.next_milestone.remaining} days until ${stats.next_milestone.days}-day badge!`
  );
}

// Weekly goal progress
if (stats.weekly_goal.current >= stats.weekly_goal.target) {
  console.log('🎉 Weekly goal achieved!');
}

​
Streak Protection

Warn users about at-risk streaks: 
if (stats.streak_status === 'at_risk') {
  alert(`⚠️ ${stats.hours_remaining}h left to maintain your ${stats.streak.current_streak}-day streak!`);
}

​
Empty State

If no entries exist: 
{
  "streak": {
    "current_streak": 0,
    "longest_streak": 0,
    "total_entries": 0,
    "this_week": 0,
    "this_month": 0,
    "last_entry_date": null
  },
  "encouragement": "Start your journaling journey today. Every story begins with one page.",
  "mood_distribution": {
    "very_positive": 0,
    "positive": 0,
    "neutral": 0,
    "negative": 0,
    "very_negative": 0
  },
  "total_words": 0,
  "average_words": 0,
  "week_chain": [...],
  "journaled_today": false,
  "hours_remaining": 12.5,
  "streak_status": "start",
  "badges": [...],
  "next_milestone": {"days": 7, "remaining": 7, "progress": 0},
  "weekly_goal": {"target": 5, "current": 0, "progress": 0}
}

​
Next Steps

Insights API

Discover patterns and correlations

Entries API

Manage journal entries

Build docs developers (and LLMs) love

Get started for freeTalk to us