Source: https://www.puesto.dev/docs/api/jobs/count-jobs
Markdown source: https://www.puesto.dev/docs/api/jobs/count-jobs.md
Description: Count the jobs matching a filter set. Accepts the same filters as Search jobs (pagination, sorting, and description knobs are ignored) and returns only the total. The default 90-day freshness window applies identically to the count. A single-country count uses the job's primary country and can be slightly lower than the number of results Search jobs returns for the same filter (jobs listing that country as a secondary location are excluded); multi-country filters count by any-listed-country, matching search exactly. Supplying `q` counts full-text matches with the same syntax, scope tiers, symbol-token handling, and guardrails as Search jobs (a broad `q` may return 422; a malformed `q`, 400). A `q` count uses any-listed-country semantics, so with a single-country filter it counts by any-listed-country (matching search), not the primary-country fast path used without `q`.

# Count jobs

`GET /api/v1/jobs/count`

Count the jobs matching a filter set. Accepts the same filters as Search jobs (pagination, sorting, and description knobs are ignored) and returns only the total. The default 90-day freshness window applies identically to the count. A single-country count uses the job's primary country and can be slightly lower than the number of results Search jobs returns for the same filter (jobs listing that country as a secondary location are excluded); multi-country filters count by any-listed-country, matching search exactly. Supplying `q` counts full-text matches with the same syntax, scope tiers, symbol-token handling, and guardrails as Search jobs (a broad `q` may return 422; a malformed `q`, 400). A `q` count uses any-listed-country semantics, so with a single-country filter it counts by any-listed-country (matching search), not the primary-country fast path used without `q`.

## Parameters

### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | No | Case-insensitive substring match on the job title (3-200 characters). |
| `q` | string | No | Full-text search across the job. Google-style syntax: quoted `"exact phrase"`, `OR`, and `-term` exclusion (a query that is ONLY exclusions is rejected with 400). Operator precedence: implicit AND binds tighter than `OR`, and a `-term` attaches only to its adjacent group — so `"machine learning" OR "data scientist" -senior` parses as `A OR (B AND NOT senior)` and CAN still return Senior ML titles. To exclude a term everywhere, distribute it across each branch: `"machine learning" -senior OR "data scientist" -senior`. By default `q` matches the job TITLE only (precise — best for common role terms); pass `q_scope=full` to also search the description. Phrase queries under `q_scope=full` combined with very narrow filters (a small country, a rare language) can hit the search timeout; the default title scope is immune, so prefer it for phrase precision. `q` composes as a filter with the standard `sort`/`cursor` pagination (newest-first over the matches) and respects the default 90-day freshness window unless a date filter is given. Symbol-bearing tech tokens (`c++`, `c#`, `.net`) are matched as a title substring instead of full-text (they collapse under English tokenization). If a full-text search yields no rows a single title-substring fallback runs and its results are flagged `fuzzy: true`. |
| `q_scope` | string | No | Which fields `q` searches. `title` (default) matches the job title only — precise, best for common role terms (e.g. `developer`, `engineer`), which otherwise match description boilerplate. `full` also searches the description — broader reach, best for niche skills or tools that appear only in the requirements text (a language or framework not named in the title). Only affects results when `q` is set (ignored otherwise). |
| `country` | string[] | No | Filter by ISO 3166-1 alpha-2 country code(s). Repeat the parameter or comma-separate values (e.g. `country=us,de`). A job matches if it is tagged with any of the given countries. Up to 20 values; case-insensitive. |
| `state` | string[] | No | Filter by state / region reference code(s). Repeat the parameter or comma-separate values (e.g. `state=CA,NY`). A job matches if it is tagged with any of the given regions. Up to 20 values; case-insensitive. |
| `city` | string | No | Case-insensitive substring match on the city name. |
| `workplace` | string | No | Filter by workplace arrangement. |
| `employment_type` | string | No | Filter by employment type. |
| `level` | string | No | Filter by seniority level. |
| `language` | string | No | Filter by ISO 639-1 language code (2 letters, case-insensitive). |
| `salary_min` | number | No | Keep jobs whose stated salary range reaches at least this amount. Jobs that state only a minimum (no maximum) match when that minimum is at least this value. |
| `salary_max` | number | No | Keep jobs whose stated salary range starts at or below this amount. |
| `salary_currency` | string | No | Filter by ISO 4217 currency code (3 letters, case-insensitive). |
| `has_salary` | boolean | No | When `true`, return only jobs that specify a salary; when `false`, only jobs without a salary. |
| `company_id` | integer | No | Filter by the numeric company id. |
| `status` | string | No | Filter by listing status. `open` (default) returns active listings; `closed` returns delisted ones. |
| `posted_since` | string | No | Only jobs posted at or after this ISO-8601 timestamp, including a UTC offset (e.g. `2024-01-01T00:00:00+00:00`). When none of `posted_since`, `posted_until`, or `first_seen_since` are provided and `status` is `open`, results default to the last 90 days. |
| `posted_until` | string | No | Only jobs posted at or before this ISO-8601 timestamp, including a UTC offset (e.g. `2024-01-01T00:00:00+00:00`). |
| `first_seen_since` | string | No | Only jobs first seen at or after this ISO-8601 timestamp, including a UTC offset (e.g. `2024-01-01T00:00:00+00:00`). |

## Response

The total number of matching jobs.

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `count` | integer | Total number of jobs matching the supplied filters. |

## Authentication

Send your secret API key (prefixed `sk_`) as a bearer token in the `Authorization` header. See [Authentication](https://www.puesto.dev/docs/authentication.md).

## Errors

Errors use the RFC 7807 `application/problem+json` format. See [Errors](https://www.puesto.dev/docs/errors.md).

## Example request

```bash
curl -X GET "https://www.puesto.dev/api/v1/jobs/count" \
  -H "Authorization: Bearer sk_your_key_here"
```

Full spec: https://www.puesto.dev/api/v1/openapi.json