> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gulp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge Status

> API reference for the knowledge status endpoint

The `/knowledge_status/{job_id}` endpoint allows you to check the status of a knowledge upload job.

## Base URL

```bash
GET https://osmosis.gulp.dev/knowledge_status/{job_id}
```

## Authentication

<RequestHeader>
  <HeaderParameter name="x-api-key" required type="string">
    Your API key
  </HeaderParameter>
</RequestHeader>

## Path Parameters

<ParamField path="job_id" type="string" required>
  The job ID for the knowledge upload, returned from the store\_knowledge endpoint
</ParamField>

## Example Requests

<CodeGroup>
  ```bash cURL
  curl -X GET https://osmosis.gulp.dev/knowledge_status/abc123 \
    -H "x-api-key: your-api-key"
  ```

  ```typescript TypeScript
  import axios from 'axios';

  async function getKnowledgeStatus(jobId: string) {
    const apiKey = process.env.OSMOSIS_API_KEY;
    
    const response = await axios.get(`https://osmosis.gulp.dev/knowledge_status/${jobId}`, {
      headers: {
        'x-api-key': apiKey
      }
    });
    
    return response.data;
  }
  ```

  ```python Python
  import os
  import requests

  def get_knowledge_status(job_id: str):
      api_key = os.getenv('OSMOSIS_API_KEY')
      
      response = requests.get(
          f"https://osmosis.gulp.dev/knowledge_status/{job_id}",
          headers={
              "x-api-key": api_key
          }
      )
      
      return response.json()
  ```

  ```go Go
  package main

  import (
      "encoding/json"
      "net/http"
      "os"
  )

  func getKnowledgeStatus(jobID string) ([]byte, error) {
      apiKey := os.Getenv("OSMOSIS_API_KEY")
      
      req, err := http.NewRequest("GET", "https://osmosis.gulp.dev/knowledge_status/"+jobID, nil)
      if err != nil {
          return nil, err
      }

      req.Header.Set("x-api-key", apiKey)

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          return nil, err
      }
      defer resp.Body.Close()

      return json.Marshal(resp)
  }
  ```
</CodeGroup>

## Response

### Success Response

<ResponseField name="status" type="string" required>
  Current status of the knowledge upload job, can be:
  `completed`, `processing` or `failed`
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

Example success response:

```json
{
  "status": "processing",
  "created_at": "2025-03-05T18:15:37.903173",
  "started_at": "2025-03-05T18:15:37.903942"
}
```

### Error Response

<ResponseField name="detail" type="array" required>
  Array of validation errors
</ResponseField>

Example error response:

```json
{
    "some_hash_key_123": {
        "status": "failed",
        "created_at": "2024-03-20T14:30:00.123456",
        "started_at": "2024-03-20T14:30:01.234567",
        "failed_at": "2024-03-20T14:30:05.345678",
        "error_message": "YWJjZGVmMTIzNDU2Nzg5MA==",
        "note": "Please provide the error_message to founders@gulp.ai alongside with the job_id"
    }
}
```

## Status Codes

<ResponseStatus code={200} status="OK">
  Successfully retrieved job status
</ResponseStatus>

<ResponseStatus code={404} status="Not Found">
  Job ID not found
</ResponseStatus>

<ResponseStatus code={422} status="Unprocessable Entity">
  Invalid request (validation error)
</ResponseStatus>

## Best Practices

1. **Job ID Management**
   * Store job IDs returned from store\_knowledge endpoint
   * Implement retry logic for failed status checks
   * Consider implementing a timeout for long-running jobs

2. **Status Monitoring**
   * Check status periodically for long-running jobs
   * Implement exponential backoff for status checks
   * Handle all possible status values appropriately

3. **Error Handling**
   * Handle 404 errors for invalid job IDs
   * Implement proper retry logic
   * Log status check failures for debugging