Skip to content
docs
Menu
#

Get Recent Sessions

Retrieve the most recent sessions across all projects

GET /api/v1/sessions/recent
On this page
#

Request

limit integer · query · default: 5

Number of sessions to return (1-100)

Authorization string · header · required

Bearer token for authentication

#

Response

success boolean

Indicates if the request was successful

data object

data

sessions array

Array of recent session objects

session

id string

Unique session identifier (UUID format)

projectId string

Associated project ID

name string

Session name

markdownSize number

Size of markdown content in bytes

rawDataSize number

Size of raw data in bytes

createdAt string

ISO 8601 creation timestamp

updatedAt string

ISO 8601 last update timestamp

startedAt string

ISO 8601 timestamp when session started

endedAt string

ISO 8601 timestamp when session ended

metadata object

metadata

clientName string

Name of the client application

clientVersion string

Version of the client application

agentName string

Name of the agent

deviceId string

Unique device identifier

gitBranches array

Array of git branches

llmModels array

Array of LLM models used

tags array

Array of session tags

total number

Total number of sessions returned

#

Request examples

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://cloud.specstory.com/api/v1/sessions/recent?limit=10"

JavaScript

const response = await fetch('https://cloud.specstory.com/api/v1/sessions/recent?limit=10', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();

Python

import requests

response = requests.get(
    'https://cloud.specstory.com/api/v1/sessions/recent',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'limit': 10}
)

data = response.json()
#

Response examples

200 Success

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "projectId": "proj_abc123",
        "name": "Feature Implementation",
        "markdownSize": 22340,
        "rawDataSize": 45678,
        "createdAt": "2024-01-20T16:30:00.000Z",
        "updatedAt": "2024-01-20T18:45:30.000Z",
        "startedAt": "2024-01-20T16:30:00.000Z",
        "endedAt": "2024-01-20T18:45:30.000Z",
        "metadata": {
          "clientName": "VSCode",
          "clientVersion": "1.85.0",
          "agentName": "SpecStory Agent",
          "deviceId": "device456",
          "gitBranches": ["feature-branch"],
          "llmModels": ["claude-3-sonnet"],
          "tags": ["feature", "api"]
        }
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "projectId": "proj_def456",
        "name": "Debug Session",
        "markdownSize": 8765,
        "rawDataSize": 15432,
        "createdAt": "2024-01-20T14:00:00.000Z",
        "updatedAt": "2024-01-20T15:30:00.000Z",
        "startedAt": "2024-01-20T14:00:00.000Z",
        "endedAt": "2024-01-20T15:30:00.000Z",
        "metadata": {
          "clientName": "Cursor",
          "clientVersion": "2.0.0",
          "agentName": "Debug Agent",
          "deviceId": "device789",
          "gitBranches": ["debug-fix"],
          "llmModels": ["gpt-4"],
          "tags": ["debugging"]
        }
      }
    ],
    "total": 2
  }
}

401 Unauthorized

{
  "success": false,
  "error": "Invalid or missing authentication token"
}