Skip to main content
GET
/
api
/
v1
/
assistants
/
{assistant_id}
/
questions
/
{question_id}
Get Question Status
curl --request GET \
  --url https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions/{question_id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_url": "https://app.wordsmith.ai/chat/550e8400-e29b-41d4-a716-446655440000",
  "status": "in_progress",
  "answer": null,
  "attachments": null
}
Retrieves the current status and results of a question that was submitted to the assistant. This endpoint is primarily used to check the progress of async questions or to retrieve results after webhook notifications.

​
Authentication

This endpoint requires a valid API key in the Authorization header.

​
Path Parameters

​
assistant_id
string
required
The ID of the assistant that processed the question. Use "default" for the general Wordsmith assistant, or the specific assistant ID used in the original request.
​
question_id
string
required
The session ID returned when the question was originally created.
curl -X GET "https://api.wordsmith.ai/api/v1/assistants/default/questions/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json"

​
Response

​
id
string
The unique identifier for this specific question.
​
session_id
string
The session ID that contains this question. This remains constant for all questions within the same conversation session.
​
session_url
string
A direct URL to view this session in the Wordsmith web application. This allows users to access the full conversation history and interact with the assistant through the web interface.
​
status
string
The current status of the question: "in_progress": The assistant is still processing your question. "completed": Processing is complete and the answer is available. "error": An error occurred during processing.
​
answer
string
The assistant’s response to your question. Only present when status is "completed".
​
attachments
array
Array of files generated by the assistant during processing. Only present when status is "completed" and files were generated.
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_url": "https://app.wordsmith.ai/chat/550e8400-e29b-41d4-a716-446655440000",
  "status": "in_progress",
  "answer": null,
  "attachments": null
}

​
Understanding IDs

​
ID vs Session ID

The response includes two important identifiers:
  • id: The unique identifier for this specific question. For the first question in a session, this equals the session_id. For follow-up questions, this is a unique feed item ID.
  • session_id: The session ID that contains this question. This remains constant for all questions within the same conversation.
Examples:
  • First question in a new session: id and session_id are the same
  • Follow-up question: id is a unique question ID, session_id is the original session ID
Use the id field to check the status of individual questions, and the session_id to identify which conversation session the question belongs to.

​
Polling Strategy

When using async mode, you can poll this endpoint to check for completion. Here’s a recommended polling strategy: 
async function waitForCompletion(questionId, maxWaitTime = 300000) {
  // 5 minutes max
  const startTime = Date.now();
  const pollInterval = 2000; // Start with 2 seconds
  let currentInterval = pollInterval;

  while (Date.now() - startTime < maxWaitTime) {
    const response = await fetch(
      `https://api.wordsmith.ai/api/v1/assistants/default/questions/${questionId}`,
      {
        headers: { Authorization: "Bearer sk-ws-api1-your_api_key_here" },
      }
    );

    const result = await response.json();

    if (result.status === "completed" || result.status === "error") {
      return result;
    }

    // Exponential backoff: increase interval up to 30 seconds
    await new Promise((resolve) => setTimeout(resolve, currentInterval));
    currentInterval = Math.min(currentInterval * 1.5, 30000);
  }

  throw new Error("Timeout waiting for question completion");
}

// Usage
try {
  const result = await waitForCompletion(
    "550e8400-e29b-41d4-a716-446655440000"
  );
  console.log("Question completed:", result);
} catch (error) {
  console.error("Failed to get result:", error);
}

​
Error Responses

{
  "error": "Question not found",
  "status": 404
}

​
File Download

When the response includes attachments, you can download them using the provided URLs: 
curl -o "contract_analysis.pdf" "https://files.wordsmith.ai/download/abc123def456"

​
Best Practices

​
Polling Guidelines

  • Start with short intervals: Begin with 2-3 second intervals for quick questions
  • Use exponential backoff: Gradually increase intervals to reduce API calls
  • Set reasonable timeouts: Most questions complete within 2-5 minutes
  • Handle errors gracefully: Always check for error status and handle appropriately

​
File Management

  • Download promptly: Attachment URLs expire after 24 hours
  • Store locally if needed: Download and store important generated files
  • Check file sizes: Large files may take time to generate and download

​
Performance Optimization

  • Use webhooks when possible: More efficient than polling for production applications
  • Cache results: Store completed responses to avoid unnecessary API calls
  • Batch requests: If checking multiple questions, consider batching your requests

​
Use Cases

  • Status checking: Monitor progress of long-running document analysis
  • Result retrieval: Get answers after receiving webhook notifications
  • Error handling: Check for and handle processing errors
  • File downloads: Retrieve generated reports and analysis documents
  • Integration workflows: Build automated systems that process legal documents