# Get response status

div
strong
🔨 In Development
 — This section is still being developed and may change.


Retrieves the current status and details of an asynchronous model response. Use this endpoint to check on responses initiated with `background: true`.

When a response is generated with background mode enabled, the API returns immediately with a response ID. Use this endpoint to poll the status and retrieve results once processing is complete.

#### Path Parameters

**`response_id`** string *required*

The unique identifier of the response to check. Returned immediately when the response was created with `background: true`.

#### Query Parameters

**`organizationId`** string *required*

The unique identifier of the organization that owns the response.

#### Response

**`id`** string

The unique identifier of the response.

**`status`** string

Current status of the response. One of:

- `processing` - Response is still being generated
- `completed` - Response generation finished successfully
- `failed` - Response generation failed with an error
- `cancelled` - Response was cancelled before completion


**`createdAt`** integer

Unix timestamp when the response was created.

**`startedAt`** integer *optional*

Unix timestamp when processing started (null if not yet started).

**`completedAt`** integer *optional*

Unix timestamp when processing completed (null if still processing).

**`progress`** object *optional*

Progress information for ongoing responses:

- `percentage` integer - Estimated completion percentage (0-100)
- `stage` string - Current processing stage (e.g., "reasoning", "tool_execution", "generating_output")
- `stepsCompleted` integer - Number of processing steps completed
- `totalSteps` integer - Estimated total processing steps


**`output`** array *optional*

Response output (only populated when `status` is `completed`). Array of output message objects with the generated content.

**`error`** object *optional*

Error details (only populated when `status` is `failed`):

- `message` string - Error description
- `code` string - Error code
- `type` string - Error type


**`usage`** object

Token/neuron usage statistics:

- `input_tokens` integer - Tokens consumed by input
- `output_tokens` integer - Tokens generated in output
- `total_tokens` integer - Total tokens used


**`model`** string

The model that was used for this response.

**`thread`** object *optional*

Thread information if the response was part of a thread:

- `id` string - Thread ID
- `messageCount` integer - Total messages in thread


**`metadata`** object *optional*

Custom metadata attached to the response.

## Returns

A [ResponseStatusResponse](#responsestatusresponse) object containing the API response data.

Check processing status

```bash
curl "https://api.freddy.aitronos.com/v1/model/response/resp_abc123?organizationId=org_abc123" \
  -H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
import requests
import os

response_id = "resp_abc123"

response = requests.get(
    f"https://api.freddy.aitronos.com/v1/model/response/{response_id}",
    headers={
        "Authorization": f"Bearer {os.environ['FREDDY_API_KEY']}"
    },
    params={
        "organizationId": "org_abc123"
    }
)

result = response.json()
print(f"Status: {result['status']}")
if result.get('progress'):
    print(f"Progress: {result['progress']['percentage']}%")
```


```javascript
const responseId = 'resp_abc123';
const response = await fetch(`https://api.freddy.aitronos.com/v1/model/response/${responseId}?organizationId=org_abc123`, {
  headers: {
    'Authorization': `Bearer ${process.env.FREDDY_API_KEY}`
  }
});

const result = await response.json();
console.log(`Status: ${result.status}`);
if (result.progress) {
  console.log(`Progress: ${result.progress.percentage}%`);
}
```

Poll until completion

```python
import requests
import os
import time

api_key = os.environ['FREDDY_API_KEY']
response_id = "resp_abc123"
org_id = "org_abc123"

while True:
    response = requests.get(
        f"https://api.freddy.aitronos.com/v1/model/response/{response_id}",
        headers={"Authorization": f"Bearer {api_key}"},
        params={"organizationId": org_id}
    )
    
    result = response.json()
    status = result['status']
    
    if status == 'completed':
        print("Response completed!")
        print(f"Output: {result['output']}")
        break
    elif status == 'failed':
        print(f"Response failed: {result['error']['message']}")
        break
    else:
        progress = result.get('progress', {})
        print(f"Status: {status}, Progress: {progress.get('percentage', 'N/A')}%")
        time.sleep(2)  # Wait 2 seconds before checking again
```


```javascript
async function pollUntilComplete(responseId, organizationId) {
  const apiKey = process.env.FREDDY_API_KEY;
  
  while (true) {
    const response = await fetch(`https://api.freddy.aitronos.com/v1/model/response/${responseId}?organizationId=${organizationId}`, {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });
    
    const result = await response.json();
    const status = result.status;
    
    if (status === 'completed') {
      console.log('Response completed!');
      console.log(`Output: ${JSON.stringify(result.output)}`);
      return result;
    } else if (status === 'failed') {
      console.error(`Response failed: ${result.error.message}`);
      throw new Error(result.error.message);
    } else {
      const progress = result.progress || {};
      console.log(`Status: ${status}, Progress: ${progress.percentage || 'N/A'}%`);
      await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
    }
  }
}

// Usage
pollUntilComplete('resp_abc123', 'org_abc123');
```

Get completed response

```bash Request
curl "https://api.freddy.aitronos.com/v1/model/response/resp_abc123?organizationId=org_abc123" \
  -H "Authorization: Bearer $FREDDY_API_KEY"
```


```json Response
{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "createdAt": 1735689600,
  "startedAt": 1735689601,
  "completedAt": 1735689615,
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Here's the analysis of your data..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 245,
    "output_tokens": 812,
    "total_tokens": 1057
  },
  "model": "gpt-4o",
  "metadata": {
    "request_id": "user_123_task_456"
  }
}
```

Error handling

```bash Request
# Response that failed
curl "https://api.freddy.aitronos.com/v1/model/response/resp_failed123?organizationId=org_abc123" \
  -H "Authorization: Bearer $FREDDY_API_KEY"
```


```json Response
{
  "id": "resp_failed123",
  "object": "response",
  "status": "failed",
  "createdAt": 1735689600,
  "startedAt": 1735689601,
  "completedAt": 1735689605,
  "error": {
    "message": "Model context length exceeded",
    "code": "context_length_exceeded",
    "type": "invalid_request_error"
  },
  "usage": {
    "input_tokens": 500,
    "output_tokens": 0,
    "total_tokens": 500
  }
}
```

## Polling Best Practices

- **Check Status Regularly**: Poll every 1-5 seconds for short-running tasks, or every 30 seconds for longer tasks
- **Exponential Backoff**: Increase polling interval over time to reduce server load (e.g., 1s → 2s → 5s → 10s)
- **Timeout Handling**: Set a maximum timeout (e.g., 1 hour) after which you stop polling
- **Error Handling**: Handle both completion failures and network errors gracefully
- **Progress Display**: Show progress percentage to users for better UX
- **Webhook Alternative**: Consider using webhooks instead of polling for better efficiency (planned feature)


## Related Resources

- [Create Response (with background mode)](/docs/api-reference/responses/create#background)
- [Response Object](/docs/api-reference/responses/object)
- [Authentication Guide](/docs/api-reference/authentication)