Get Question Status

Retrieve the status and results of a previously submitted question

GET /api/v1/assistants/{assistant_id}/questions/{question_id}

Get Question Status

cURL

curl --request GET \
  --url https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions/{question_id} \
  --header 'Authorization: Bearer <token>'

In Progress

{
  "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,
  "reason": 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 id returned when the question was originally created. This addresses that specific question — for the first question in a session it equals the session ID, and for follow-up questions it is a distinct question ID. See Understanding IDs.

cURL

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. null only when status is "filtered", where no session was created.

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. null only when status is "filtered", where there is no session to view.

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. "filtered": The assistant declined the question, so nothing was processed and no session exists — see Filtered questions.

"completed", "error" and "filtered" are all terminal: once returned, a question’s status never changes again. Only "in_progress" is worth polling on.

answer · string

The assistant’s response to your question. Present when status is "completed", and also when it is "filtered" — where it carries the decline wording, so a client that only reads answer still has something to show. See Filtered questions.

attachments · array

Array of files generated by the assistant during processing. Only present when status is "completed" and files were generated.

Show Attachment Object

file_name · string

The name of the generated file

content_type · string

The MIME type of the file (e.g., “application/pdf”, “text/plain”)

content_length · integer

The size of the file in bytes

url · string

A presigned URL to download the file. This URL expires after 24 hours.

reason · string

One sentence explaining why the assistant declined this particular question, stored when it was filtered and returned unchanged on every later poll. Present only when status is "filtered", and null for every other status. answer carries the same sentence, unless the assistant’s owner has set fixed wording to return instead. Both can be null on a filtered question — questions filtered before these fields existed have no stored explanation — so show them when they are there rather than depending on them.

In Progress

{
  "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,
  "reason": 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, and is null for a filtered question.

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
• Filtered question: id names the question itself, session_id is null because no session was created

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. Stop on any terminal status — "completed", "error" or "filtered" — and treat everything else as still in flight. A loop that waits only for "completed" or "error" polls a filtered question until it times out.

Here’s a recommended polling strategy:

JavaScript - Polling Example

const TERMINAL_STATUSES = ["completed", "error", "filtered"];

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();

    // Stop on every terminal status, including "filtered" — a filtered
    // question never progresses, so waiting on it would spin until timeout.
    if (TERMINAL_STATUSES.includes(result.status)) {
      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"
  );
  if (result.status === "filtered") {
    console.log("The assistant declined this question:", result.id);
  } else {
    console.log("Question completed:", result);
  }
} catch (error) {
  console.error("Failed to get result:", error);
}

Error Responses

See the Errors page for the full error format reference.

404 Not Found

{
  "error_code": "resource_not_found",
  "ws_api_error_code": "resource_not_found",
  "message": "Question not found for this assistant."
}

File Download

When the response includes attachments, you can download them using the provided URLs:

cURL - Download Attachment

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
• Stop on every terminal status: "completed", "error" and "filtered" are all final — never poll past one
• 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