Skip to main content
GET
/
api
/
public
/
thread
/
{id}
Get Session
curl --request GET \
  --url https://api.nexusgpt.io/api/public/thread/{id} \
  --header 'api-key: <api-key>'
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "topic": "Order Support - #12345",
  "status": "ACTIVE",
  "createdAt": "2024-01-20T10:30:00Z",
  "lastMessageAt": "2024-01-20T10:45:30Z",
  "messageCount": 8,
  "metadata": {
    "agentId": "agt_abc123",
    "integrationId": "int_xyz789"
  }
}

​
Get Session

Retrieves detailed information about a specific chat session, including its status, topic, and metadata.

​
Endpoint

GET https://api.nexusgpt.io/api/public/thread/{id}

​
Authentication

​
api-key
string
required
Your Nexus API key for authentication

​
Path Parameters

​
id
string
required
The unique identifier of the session to retrieve
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "topic": "Order Support - #12345",
  "status": "ACTIVE",
  "createdAt": "2024-01-20T10:30:00Z",
  "lastMessageAt": "2024-01-20T10:45:30Z",
  "messageCount": 8,
  "metadata": {
    "agentId": "agt_abc123",
    "integrationId": "int_xyz789"
  }
}

​
Response Fields

​
id
string
required
Unique identifier for the session
​
topic
string
Auto-generated topic based on the conversation content. May be null for new sessions.
​
status
string
required
Current status of the session
  • ACTIVE - Session is active and can receive messages
  • EXPIRED - Session has expired due to inactivity
  • CLOSED - Session was manually closed
​
createdAt
string
required
ISO 8601 timestamp of when the session was created
​
lastMessageAt
string
ISO 8601 timestamp of the most recent message in the session
​
messageCount
number
Total number of messages in the conversation
​
metadata
object
Additional metadata about the session

​
Example Usage

curl -X GET https://api.nexusgpt.io/api/public/thread/550e8400-e29b-41d4-a716-446655440000 \
  -H "api-key: YOUR_API_KEY"

​
Common Use Cases

​
1. Session Health Check

async function isSessionActive(sessionId) {
  try {
    const session = await getSession(sessionId);
    return session.status === 'ACTIVE';
  } catch (error) {
    if (error.response?.status === 404) {
      return false;
    }
    throw error;
  }
}

​
2. Session Monitoring

async function monitorSession(sessionId) {
  const session = await getSession(sessionId);
  
  // Check if session is stale
  const lastMessageTime = new Date(session.lastMessageAt);
  const timeSinceLastMessage = Date.now() - lastMessageTime.getTime();
  const isStale = timeSinceLastMessage > 30 * 60 * 1000; // 30 minutes
  
  return {
    id: session.id,
    isActive: session.status === 'ACTIVE',
    isStale,
    messageCount: session.messageCount,
    topic: session.topic
  };
}

​
3. Session Analytics

async function getSessionAnalytics(sessionIds) {
  const analytics = {
    total: sessionIds.length,
    active: 0,
    expired: 0,
    avgMessageCount: 0,
    topics: []
  };
  
  let totalMessages = 0;
  
  for (const id of sessionIds) {
    try {
      const session = await getSession(id);
      
      if (session.status === 'ACTIVE') analytics.active++;
      if (session.status === 'EXPIRED') analytics.expired++;
      
      totalMessages += session.messageCount;
      if (session.topic) analytics.topics.push(session.topic);
      
    } catch (error) {
      // Handle errors (e.g., deleted sessions)
    }
  }
  
  analytics.avgMessageCount = totalMessages / sessionIds.length;
  return analytics;
}

​
Error Responses

{
  "statusCode": 404,
  "message": "Session not found",
  "error": "Not Found"
}

​
Session Lifecycle

1

Creation

Session is created with status ACTIVE
2

Active Period

Session remains active for 24 hours after the last message
3

Expiration Warning

Sessions nearing expiration can be extended by sending a new message
4

Expiration

After 24 hours of inactivity, status changes to EXPIRED

​
Best Practices

  • Cache session information to reduce API calls
  • Invalidate cache when sending new messages
  • Set appropriate TTL based on your use case
  • Handle 404 errors gracefully
  • Don’t retry 404 errors
  • Log session IDs for debugging
  • Periodically check session status
  • Alert on unexpected session expiration
  • Track session metrics for optimization