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

# List background jobs

> Your background jobs, newest first: every one, or only the open ones.

This lists the jobs you started here and the ones your in-app agents started. `open=true` keeps only jobs still `queued` or `running`. `origin_kind` keeps one kind of starter: `session` (a chat session), `igris` (Igris), `brain` (a workflow's Brain), or `api` (the API or an AI assistant). `origin_id` keeps the jobs one session or workflow started. Each item has the fields of [Get a background job](/api-reference/jobs/get).

Needs `jobs:read`. MCP tool: `list_jobs`.


## OpenAPI

````yaml GET /v1/jobs
openapi: 3.1.0
info:
  title: Valendata REST API
  version: 1.0.0
  description: >-
    Create, run, schedule, and improve skills and workflows over JSON and HTTPS.
    Every route is under `/v1`; changes inside v1 are additive only (new routes,
    new optional parameters, new response fields). A route that will go away is
    marked `deprecated` here and answers with `Deprecation`, `Sunset` and a
    `Link` to its replacement for at least six months before it is removed.
    Errors, limits, pagination and idempotency:
    https://docs.valendata.com/api-reference/errors.
  license:
    name: Proprietary
    url: https://www.valendata.com/terms-and-conditions
servers:
  - url: https://api.valendata.com
    description: Production
security:
  - ApiKeyAuth: []
  - ApiKeyHeader: []
tags:
  - name: Skills
    description: List, create, read, update, and delete skills.
  - name: Marketplace
    description: Find a skill by the task, with its price per run and track record.
  - name: Runs
    description: Run skills and workflows, read any run, and cancel one.
  - name: Skill versions
    description: List, compare, restore, and pin a skill's versions.
  - name: Improvements
    description: >-
      Fix a skill, add fields, or re-learn its detail steps, and read its change
      history.
  - name: Schedules
    description: Run a skill or workflow on a fixed cadence.
  - name: Workflows
    description: List, create, read, update, and delete workflows.
  - name: Logins
    description: Saved website logins a skill can sign in with.
  - name: Connected apps
    description: >-
      Your own accounts (Gmail, Calendar, Slack …): connect them, list their
      tools, and run one.
  - name: Follow-ups
    description: >-
      Wait for something to arrive (a code, a link, a file, a message) or check
      back later, and read what came.
  - name: Jobs
    description: >-
      What your agents started to run in the background (skill runs, workflow
      runs, research), what came back, and stopping it.
  - name: Notes
    description: >-
      The notes on your Notes page: list and search them, read one, write,
      change, and delete them.
  - name: Account and usage
    description: Your plan, credit balance, and usage.
  - name: Webhooks
    description: The secret that signs webhook deliveries.
paths:
  /v1/jobs:
    get:
      tags:
        - Jobs
      summary: List background jobs
      description: >-
        Your background jobs, newest first: skill runs, workflow runs and
        research that your in-app agents (the assistant, a chat session) or you
        over the API started to run on their own. `open=true` keeps the ones
        still `queued` or `running`; `origin_kind` (`session`, `igris`, `brain`,
        `api`) and `origin_id` keep the ones one agent or chat started. Page
        with `limit` (1–100) and `cursor`. Needs `jobs:read`.
      operationId: list_jobs
      parameters:
        - name: open
          in: query
          required: false
          schema:
            type: boolean
            description: 'Only jobs still queued or running. Default: every one.'
            default: false
            title: Open
          description: 'Only jobs still queued or running. Default: every one.'
          example: true
        - name: origin_kind
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - igris
                  - session
                  - brain
                  - api
                type: string
              - type: 'null'
            description: Only jobs started by this kind of caller.
            title: Origin Kind
          description: Only jobs started by this kind of caller.
          example: session
        - name: origin_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 255
              - type: 'null'
            description: Only jobs started by this session or workflow.
            title: Origin Id
          description: Only jobs started by this session or workflow.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: Items per page, 1–100.
            default: 100
            title: Limit
          description: Items per page, 1–100.
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: next_cursor of the previous page.
            title: Cursor
          description: next_cursor of the previous page.
      responses:
        '200':
          description: A page of your background jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobList'
              example:
                jobs:
                  - id: job_3f9a1c2b7d4e
                    origin_kind: session
                    origin_id: sess_8c1d2e3f
                    group_id: null
                    kind: skill
                    label: eBay search
                    target_id: skl_ebay_listings
                    run_ref: run_5b6c7d8e9f0a
                    status: completed
                    summary: 12 results
                    result:
                      count: 12
                      preview:
                        - title: Nikon F3 body
                          price: $289
                        - title: Nikon F3HP, boxed
                          price: $340
                    error: null
                    cancel_requested: false
                    attempts: 1
                    created_at: '2026-10-10T09:00:00Z'
                    started_at: '2026-10-10T09:00:01Z'
                    ended_at: '2026-10-10T09:02:40Z'
                    link: /skills/runs/run_5b6c7d8e9f0a
                next_cursor: null
                has_more: false
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - ApiKeyAuth: []
        - ApiKeyHeader: []
components:
  schemas:
    JobList:
      properties:
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: Pass as ?cursor= for the next page; null on the last page.
        jobs:
          items:
            $ref: '#/components/schemas/Job'
          type: array
          title: Jobs
        has_more:
          type: boolean
          title: Has More
          description: True when there is a next page (next_cursor is not null).
          readOnly: true
      type: object
      required:
        - jobs
        - has_more
      title: JobList
    Job:
      properties:
        id:
          type: string
          title: Id
        origin_kind:
          type: string
          enum:
            - session
            - igris
            - brain
            - api
          title: Origin Kind
          description: >-
            Who started it: `session` (a chat session's agent), `igris` (the
            assistant), `brain` (a workflow's Brain, which may report results)
            or `api`.
        origin_id:
          type: string
          title: Origin Id
          description: >-
            The session or workflow that started it; empty for the assistant and
            the API.
          default: ''
        group_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Group Id
          description: The batch job it belongs to, when several were started together.
        kind:
          type: string
          enum:
            - skill
            - workflow
            - research
            - batch
          title: Kind
          description: >-
            What it runs: a `skill`, a `workflow`, a `research` helper, or a
            `batch` grouping jobs started together.
        label:
          type: string
          title: Label
          description: What it is, in the words it was started with, e.g. 'eBay search'.
          default: ''
        target_id:
          type: string
          title: Target Id
          description: The skill or workflow it runs.
          default: ''
        run_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Run Ref
          description: >-
            The run it drives (GET /v1/runs/{run_id} for a skill or workflow);
            null until it has started.
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - failed
            - cancelled
          title: Status
          description: '`queued`, `running`, then one of `completed`, `failed`, `cancelled`.'
        summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Summary
          description: One plain line of what came back, once it ended.
        result:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Result
          description: >-
            A small result: `count` and a `preview` of the first rows. The run
            has the rest.
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Why it failed.
        cancel_requested:
          type: boolean
          title: Cancel Requested
          description: A stop was asked for; it ends `cancelled` soon.
          default: false
        attempts:
          type: integer
          title: Attempts
          description: How many times its run was started.
          default: 0
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        ended_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ended At
        link:
          type: string
          title: Link
          description: >-
            The path of the page in the Valendata app that shows its run (e.g.
            /skills/runs/run_…); empty until it has started.
          default: ''
      type: object
      required:
        - id
        - origin_kind
        - kind
        - status
      title: Job
    Error:
      type: object
      required:
        - detail
        - code
        - type
        - request_id
      properties:
        detail:
          description: What went wrong. A string, or an object for errors with more to say.
          oneOf:
            - type: string
            - additionalProperties: true
              type: object
        code:
          type: string
          description: >-
            Stable machine-readable code. Known values: `bad_request`,
            `invalid_json`, `invalid_cursor`, `invalid_idempotency_key`,
            `unauthorized`, `payment_required`, `permission_denied`,
            `not_found`, `method_not_allowed`, `conflict`, `app_not_connected`,
            `idempotency_key_in_use`, `idempotent_replay_unavailable`,
            `payload_too_large`, `unsupported_media_type`, `validation_error`,
            `idempotency_key_reused`, `rate_limited`, `internal_error`,
            `upstream_error`, `service_unavailable`.
          example: not_found
        type:
          type: string
          enum:
            - invalid_request_error
            - authentication_error
            - billing_error
            - permission_error
            - conflict_error
            - idempotency_error
            - rate_limit_error
            - api_error
          description: The broad category of the error.
        request_id:
          type: string
          description: Also in the `X-Request-ID` header.
          example: 3f9a1c2b7d4e
        param:
          type: string
          description: >-
            The field at fault, on validation errors (dotted path, e.g.
            `inputs.city`).
        errors:
          type: array
          items:
            additionalProperties: true
            type: object
          description: Every validation problem, on a 422 from request validation.
  headers:
    X-Request-ID:
      description: >-
        This request's id (yours, if you sent a valid `X-Request-ID`). Quote it
        to support.
      schema:
        type: string
    X-RateLimit-Limit:
      description: Requests a minute this API key may make.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current minute.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix time (seconds) the current window ends.
      schema:
        type: integer
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    BadRequest:
      description: >-
        The request is malformed: the body is not JSON, the cursor or
        Idempotency-Key is not valid.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              The request is malformed: the body is not JSON, the cursor or
              Idempotency-Key is not valid.
            code: invalid_json
            type: invalid_request_error
            request_id: 3f9a1c2b7d4e
    Unauthorized:
      description: The API key is missing, malformed, revoked, or expired.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: The API key is missing, malformed, revoked, or expired.
            code: unauthorized
            type: authentication_error
            request_id: 3f9a1c2b7d4e
    Forbidden:
      description: >-
        The key lacks a scope, is limited to other skills or workflows, or you
        may not do this.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              The key lacks a scope, is limited to other skills or workflows, or
              you may not do this.
            code: permission_denied
            type: permission_error
            request_id: 3f9a1c2b7d4e
    Unprocessable:
      description: >-
        A field is invalid (`param` names it), or the Idempotency-Key was used
        with a different request.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: 'Invalid request — name: Field required'
            code: validation_error
            type: invalid_request_error
            request_id: 3f9a1c2b7d4e
            param: name
            errors:
              - type: missing
                loc:
                  - body
                  - name
                msg: Field required
    RateLimited:
      description: >-
        Too many requests for this key, or too many runs in progress. Wait
        `Retry-After` seconds.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              Too many requests for this key, or too many runs in progress. Wait
              `Retry-After` seconds.
            code: rate_limited
            type: rate_limit_error
            request_id: 3f9a1c2b7d4e
    InternalError:
      description: >-
        Something broke on our side. Retry; runs that fail on our side are
        refunded.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              Something broke on our side. Retry; runs that fail on our side are
              refunded.
            code: internal_error
            type: api_error
            request_id: 3f9a1c2b7d4e
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: vd_sk_...
      description: >-
        API key with the `vd_sk_` prefix, as `Authorization: Bearer vd_sk_...`.
        Create keys in Settings → API Keys.
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: The same API key in the `x-api-key` header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.