---
title: "List jobs"
method: GET
path: "/jobs"
tags: ["Jobs"]
---

# List jobs

`GET /jobs`

## Request

- Base URL: `https://api.cavuno.com/v1`
- URL: `https://api.cavuno.com/v1/jobs`
- Auth: HTTP bearer

Returns a list of your jobs. The jobs are returned sorted by creation date, with the most recently created jobs appearing first.

## Query parameters

- `cursor` string: An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results.
- `limit` integer: A limit on the number of objects to be returned. Limit can range between 1 and 100.
- `status` 'draft' | 'published' | 'expired' | 'archived' | 'pending_approval': Only return jobs matching the given status. One of `draft`, `published`, `expired`, `archived`, or `pending_approval` (awaiting operator approval). `draft` does not include jobs awaiting approval.
- `companyId` string: Only return jobs at the company with the given ID.
- `applicationUrl` string: Only return jobs matching this application URL. URLs are normalized server-side (casing, tracking params, etc.) so equivalent links match. Useful for deduplication lookups.
- `externalId` string: Only return jobs with this `externalId`. Useful for deduplication lookups when reposting from an ATS.

## Response `200`

Successful response.

- object
  - `object` 'list', required
  - `url` string, required
  - `hasMore` boolean, required
  - `nextCursor` string, nullable, required
  - `data` JobSummary[], required
    - `id` string, required: Unique identifier for the object. Use this value as the `{id}` path parameter for the job endpoints (e.g. `GET /v1/jobs/{id}`).
    - `object` 'job', required: String representing the object's type. Objects of the same type share the same value.
    - `title` string, required: The job title.
    - `slug` string, nullable, required: URL-friendly slug used in public board URLs, or `null` if no slug is set.
    - `status` 'draft' | 'published' | 'expired' | 'archived' | 'pending_approval', required: Current status of the job. One of `draft`, `published`, `expired`, `archived`, or `pending_approval`. A `pending_approval` job is waiting for an operator to approve it: approve with `POST /v1/jobs/:id/publish`, reject with `DELETE /v1/jobs/:id`. It is not public, like a draft.
    - `companyId` string, nullable, required: Identifier of the company the job belongs to, or `null` if no company is attached.
    - `employmentType` 'full_time' | 'part_time' | 'contract' | 'internship' | 'temporary' | 'volunteer' | 'other', nullable, required: Employment type of the role, or `null` if not specified. For a job with a custom employment type, this is the Google equivalent of the custom type.
    - `customEmploymentType` object, nullable, required: The board's custom employment type for this job (for example `Casual`), or `null` when the job uses a built-in type only. A deleted custom type reads back as `null` and the job shows its built-in `employmentType`.
      - `key` string, required: Stable key of the custom employment type. Never changes.
      - `label` string, required: Display name of the custom employment type, as configured.
    - `remoteOption` 'on_site' | 'hybrid' | 'remote', nullable, required: Whether the role is on-site, hybrid, or fully remote. `null` only on older jobs saved without one; create requires it and `PATCH` cannot clear it.
    - `seniority` 'entry_level' | 'associate' | 'mid_level' | 'senior' | 'lead' | 'principal' | 'director' | 'executive', nullable, required: Seniority level of the role, or `null` if not specified.
    - `salaryMin` number, nullable, required: Minimum salary in `salaryCurrency` units, or `null` if not specified.
    - `salaryMax` number, nullable, required: Maximum salary in `salaryCurrency` units, or `null` if not specified.
    - `salaryCurrency` string, nullable, required: Three-letter ISO 4217 currency code for the salary range, or `null` if no salary is specified.
    - `salaryTimeframe` 'per_year' | 'per_month' | 'per_week' | 'per_day' | 'per_hour', nullable, required: Period the salary range is quoted against, or `null` if no salary is specified.
    - `isFeatured` boolean, required: Whether the job appears in featured slots on the public board.
    - `publishedAt` string, nullable, required: Time at which the job was first published, or `null` if not yet published. ISO 8601 datetime.
    - `expiresAt` string, nullable, required: Time at which the job expires as an ISO 8601 datetime. `null` can appear when the expiry requirement does not apply, including for drafts and sponsored jobs; ordinary published jobs always have an expiry.
    - `createdAt` string, required: Time at which the job was created. ISO 8601 datetime.
    - `updatedAt` string, required: Time at which the job was last updated. ISO 8601 datetime.
    - `revision` integer, required: Monotonic Job lifecycle revision used to reconcile webhook events. Legacy rows are 0 until the rollout backfill runs.
    - `skills` string[], required: Canonical skill slugs assigned to the job.
    - `categories` string[], required: Canonical category slugs assigned to the job.
    - `externalId` string, nullable, required: External identifier supplied by the caller on create, used for deduplication via `GET /v1/jobs?externalId=...`. `null` when no external identifier was set.
    - `customFieldValues` object, required: Board-defined custom-field values for this job, keyed by the field `key` (the definitions are published at `GET /v1/settings/job-form`). Each value is returned as stored: a string (`short_text` / `long_text` / a `single_select` option key), a string array (`multi_select` option keys), a boolean, or a number. Always an object: `{}` when the job has no custom-field values, never `null` or a missing field. Only real values are stored, so this never contains `null` or empty values.
    - `collectionValues` object, required: Operator-facing collection record IDs keyed by job collection field. Always an object; values are arrays even for single-select fields.
    - `links` AdminOnlyResourceLinks, required: Links related to this resource. List responses carry the operator URL; detail responses may also carry the public URL.
      - `admin` string, uri, required: URL inside the Cavuno app where the authenticated owner can manage this resource.

## Other responses

- `400`: The request was malformed.

## Changes

- **2026-10-19** `c34152c38176`: 1 info
  - added the optional property `error/upgrade` to the response with the `400` status

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/jobs/get.md)

---

[API](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api.md) · [All operations](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/revisions/d5974dabff14?raw)