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

# Get Search Job Status

> Poll the status of a running search job. Returns progress and the full result set when the job completes.

## Polling Pattern

Search jobs usually resolve in 1-8 seconds (occasional automatic retries take a bit longer), but they still go through the same async job pattern as scrape and crawl for consistency.

```javascript theme={null}
async function waitForResult(jobId) {
  while (true) {
    const res = await fetch(`https://api.spidra.io/api/search/${jobId}`, {
      headers: { Authorization: 'Bearer YOUR_API_KEY' }
    });
    const data = await res.json();

    if (data.status === 'completed') return data.result;
    if (data.status === 'failed') throw new Error(data.error);

    await new Promise(r => setTimeout(r, 1500));
  }
}
```

***

## Response Structure

```json theme={null}
{
  "status": "completed",
  "progress": { "message": "Search completed successfully", "progress": 1 },
  "result": {
    "success": true,
    "data": {
      "web": [
        { "title": "...", "url": "...", "description": "...", "position": 1 }
      ]
    },
    "stats": {
      "durationMs": 1714
    }
  },
  "error": null
}
```

### result.data

One key per requested source (`web`, `news`, `images`, `videos`), each an array of result objects. Fields vary slightly by source:

| Field          | Sources              | Description                       |
| -------------- | -------------------- | --------------------------------- |
| `title`        | all                  | Result title                      |
| `url`          | all                  | Link to the result                |
| `description`  | web, news            | Snippet text                      |
| `position`     | all                  | 1-indexed rank within that source |
| `imageUrl`     | images               | Full-size image URL               |
| `thumbnailUrl` | images, news, videos | Thumbnail URL                     |
| `source`       | news                 | Publisher name                    |
| `date`         | news, videos         | Relative or absolute date string  |
| `duration`     | videos               | Video length, e.g. `"12:43"`      |

### result.stats

| Field        | Description                                  |
| ------------ | -------------------------------------------- |
| `durationMs` | How long the whole job took, in milliseconds |

<Note>
  `result.success: false` with an empty `data` object means Spidra could not retrieve results for every requested source after retrying — this is rare, but is a normal "no results" outcome, not treated as a hard error, and isn't billed.
</Note>


## OpenAPI

````yaml GET /search/{jobId}
openapi: 3.1.0
info:
  title: Spidra API
  version: 1.0.0
  description: >-
    Public API endpoints for web scraping via Spidra. Authenticate with
    `Authorization: Bearer YOUR_API_KEY`.
servers:
  - url: https://api.spidra.io/api
security:
  - BearerAuth: []
  - ApiKeyAuth: []
paths:
  /search/{jobId}:
    get:
      tags:
        - Search
      summary: Get Search Job Status
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
          description: The job ID returned from POST /search
      responses:
        '200':
          description: Job status and results
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/JobStatus'
                  progress:
                    type: object
                    properties:
                      message:
                        type: string
                      progress:
                        type: number
                        minimum: 0
                        maximum: 1
                  result:
                    $ref: '#/components/schemas/SearchResult'
                    nullable: true
                    description: Present only when status is 'completed'
                  error:
                    type: string
                    nullable: true
              examples:
                in_progress:
                  summary: Job in progress
                  value:
                    status: active
                    progress:
                      message: Trying google for web...
                      progress: 0.3
                    result: null
                    error: null
                completed:
                  summary: Job completed
                  value:
                    status: completed
                    progress:
                      message: Search completed successfully
                      progress: 1
                    result:
                      success: true
                      data:
                        web:
                          - title: Dynamics of Flight
                            url: >-
                              https://www.grc.nasa.gov/www/k-12/UEET/StudentSite/dynamicsofflight.html
                            position: 1
                      stats:
                        durationMs: 1714
                    error: null
        '403':
          description: Not authorized to access this job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: error
                message: You do not have permission to access this job.
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: error
                message: Search job not found
components:
  schemas:
    JobStatus:
      type: string
      enum:
        - waiting
        - active
        - completed
        - failed
        - delayed
      description: Current status of the scrape job
    SearchResult:
      type: object
      properties:
        success:
          type: boolean
          description: >-
            False only when no results could be retrieved for any requested
            source
        data:
          type: object
          properties:
            web:
              type: array
              items:
                $ref: '#/components/schemas/SearchResultItem'
            news:
              type: array
              items:
                $ref: '#/components/schemas/SearchResultItem'
            images:
              type: array
              items:
                $ref: '#/components/schemas/SearchResultItem'
            videos:
              type: array
              items:
                $ref: '#/components/schemas/SearchResultItem'
          description: One key per requested source
        stats:
          type: object
          properties:
            durationMs:
              type: integer
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
      required:
        - status
        - message
    SearchResultItem:
      type: object
      properties:
        title:
          type: string
        url:
          type: string
        description:
          type: string
          description: Snippet text (web/news only)
        position:
          type: integer
          description: 1-indexed rank within that source
        imageUrl:
          type: string
          description: Full-size image URL (images only)
        thumbnailUrl:
          type: string
          description: Thumbnail URL (images/news/videos)
        source:
          type: string
          description: Publisher name (news only)
        date:
          type: string
          description: Relative or absolute date string (news/videos)
        duration:
          type: string
          description: Video length, e.g. "12:43" (videos only)
      required:
        - title
        - url
        - position
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````