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

# List your service jobs



## OpenAPI

````yaml /openapi.yaml get /v1/services/jobs
openapi: 3.1.0
info:
  title: Retriever Public API
  version: 1.0.0
  description: >
    Retriever public API: start the prospecting agent (runs), read and export

    tables, import data, sync exclusion lists, run structured research (Go),

    and call atomic services.


    **Model Context Protocol (MCP)**: the same account and credits are available

    through the hosted MCP server (`POST /mcp`, Streamable HTTP). See the MCP

    guide in this documentation (Model Context Protocol navigation). Primary

    tools: `service_discover`, `service_execute`, `retriever_build_list_start`,

    `table_*`, `sequence_*`, `inbox_*`.


    **Authentication**: `Authorization: Bearer ret_live_…`. Create the key in
    the

    app: Settings → **API keys** → **Create API key**. The key grants access to

    resources in the key owner's organization.


    **Errors**: every HTTP error has the shape

    `{ "error": { "code": "…", "message": "…", "details": … } }`.

    Branch your code on `error.code` (stable), never on `message`.


    **Rate limits**: key-authenticated responses include

    `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (seconds).

    A `429` response also includes `Retry-After` (seconds).


    API error messages are in English.
  contact:
    name: Retriever
servers:
  - url: https://api.retriever.run
    description: Production
  - url: http://localhost:4320
    description: Local app-server
security:
  - bearerAuth: []
tags:
  - name: Runs
    description: Prospecting agent « prompt in, table out ». Asynchronous.
  - name: Tables
    description: Read live tables in a workspace.
  - name: Workspaces
    description: Create workspaces and import tables.
  - name: Exclusions
    description: Company and people lists to never source.
  - name: Go
    description: Autonomous web research and structured extraction.
  - name: Services
    description: Atomic services (search, scraping, email…).
  - name: Credits
    description: Credit balance.
paths:
  /v1/services/jobs:
    get:
      tags:
        - Services
      summary: List your service jobs
      operationId: listServiceJobs
      parameters:
        - name: service
          in: query
          schema:
            type: string
          description: Filter by service.
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Jobs, newest to oldest.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceJob'
                  next_offset:
                    type: integer
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    ServiceJob:
      type: object
      properties:
        ok:
          type: boolean
        job_id:
          type: string
        service:
          type: string
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - failed
            - cancelled
        attempt:
          type: integer
          description: >-
            Number of execution attempts. Becomes 2 if a restart resumed the
            job.
        result:
          type: object
          description: Present only if `completed`.
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          description: Present only if `failed`.
        created_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        poll_url:
          type: string
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable code; use in your application.
            message:
              type: string
              description: Human-readable explanation. May change.
            details:
              description: Optional details (e.g. list of invalid fields).
  responses:
    Unauthorized:
      description: >-
        `not_authenticated`: missing header, malformed (expected `Bearer
        <key>`), revoked or unknown key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_authenticated
              message: A valid API key is required.
    TooManyRequests:
      description: '`rate_limited`: wait `Retry-After` seconds, then retry.'
      headers:
        Retry-After:
          schema:
            type: integer
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded. Retry later.
  headers:
    RateLimit-Limit:
      schema:
        type: integer
      description: Window budget.
    RateLimit-Remaining:
      schema:
        type: integer
      description: Remaining requests.
    RateLimit-Reset:
      schema:
        type: integer
      description: Seconds until reset.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key `ret_live_…` created in Settings → API keys.

````