Skip to main content

​
Overview

GitaChat automatically tracks your search history, allowing you to revisit verses you’ve previously explored. This feature helps you keep track of your spiritual journey and easily return to verses that were meaningful to you.

​
How History Works

Automatic Tracking

Every search query is automatically saved to your history

Chronological Order

View your searches in reverse chronological order (newest first)

Easy Access

Quickly revisit verses you’ve searched before

Clear History

Delete all history with a single action

​
API Endpoint

The history API is available at /api/history and supports two HTTP methods:

​
Get Search History

Retrieve all search queries for the authenticated user. Endpoint: GET /api/history Authentication: Required (Clerk) Rate Limit: 30 requests per minute per client Response: 
[
  {
    "id": "uuid",
    "user_id": "user_123",
    "chapter": 2,
    "verse": 47,
    "query": "duty without attachment",
    "created_at": "2024-03-10T12:00:00Z"
  },
  {
    "id": "uuid",
    "user_id": "user_123",
    "chapter": 18,
    "verse": 66,
    "query": "surrender to Krishna",
    "created_at": "2024-03-10T11:30:00Z"
  }
]
Response Fields:
  • id: Unique identifier for the history entry
  • user_id: Clerk user identifier
  • chapter: Chapter number of the verse
  • verse: Verse number
  • query: The original search query text
  • created_at: Timestamp when the search was performed

​
Clear All History

Delete all search history for the authenticated user. Endpoint: DELETE /api/history Authentication: Required (Clerk) Rate Limit: 5 requests per minute per client (stricter for destructive operations) Success Response (200): 
{
  "success": true
}

​
Data Storage

Search history is stored in the query_history table in Supabase:
ColumnTypeDescription
idUUIDPrimary key
user_idStringClerk user identifier
chapterIntegerChapter number (1-18)
verseIntegerVerse number
queryTextOriginal search query
created_atTimestampWhen the search was performed
The table is indexed on user_id and created_at for efficient querying.

​
Implementation Details

The history system is implemented in /app/api/history/route.ts:

Separate Rate Limits

GET: 30 req/min, DELETE: 5 req/min to prevent abuse

Automatic Recording

Searches are logged automatically by the main query endpoint

User Isolation

Each user can only access their own history

Ordered Results

Results always sorted by most recent first

​
How History is Recorded

When you search for a verse or topic in GitaChat, the query is automatically saved to your history through the main search API. This happens seamlessly in the background without any action required from you. The recording process:
  1. User submits a search query
  2. GitaChat processes the query and returns relevant verses
  3. Query details (chapter, verse, query text) are saved to query_history
  4. History entry includes timestamp for chronological sorting

​
Daily Verse Integration

Your search history also plays a role in the daily verse feature. The daily verse selection algorithm:
  1. Checks which verses you’ve already seen (from history)
  2. Prioritizes showing you new, unseen verses
  3. Falls back to random selection if all verses have been seen
This ensures you receive fresh content daily and gradually explore the entire Bhagavad Gita.

​
User Interface

The history feature integrates into the GitaChat UI:
  1. View History: Access a dedicated history page showing all past searches
  2. Click to Revisit: Click any history item to view that verse again
  3. Clear All: Button to delete entire history if desired
  4. Timestamp Display: See when each search was performed

​
Privacy and Data Management

Privacy Controls

  • Only you can see your search history
  • History is tied to your Clerk user ID
  • Clear all history anytime with DELETE endpoint
  • History data is stored securely in Supabase

​
Rate Limiting

Different rate limits apply to different operations:
OperationRate LimitPurpose
GET (view history)30 requests/minNormal browsing usage
DELETE (clear history)5 requests/minPrevent accidental mass deletions

​
Error Handling

Common error scenarios:
ErrorStatusDescription
Unauthorized401User not logged in
Too many requests429Rate limit exceeded
Database not configured503Supabase connection unavailable
Failed to fetch/clear500Server error occurred

​
Use Cases

Personal Review

Review verses you’ve explored in your spiritual journey

Revisit Favorites

Quickly find verses that resonated with you before

Study Patterns

See which topics you search for most frequently

Daily Verse Optimization

History helps ensure you see new verses daily

​
Best Practices

  • Regular Review: Periodically review your history to reinforce learning
  • Bookmark Important Verses: Use bookmarks for verses you want to save permanently
  • Clear Old History: Clear history periodically if you want a fresh start
  • Combine with Notes: Add notes to verses in your history for deeper reflection

Build docs developers (and LLMs) love

Get started for freeTalk to us