---
title: "List project keywords"
method: GET
path: "/projects/{project_id}/keywords"
tags: ["keywords"]
---

# List project keywords

`GET /projects/{project_id}/keywords`

## Request

- Base URL: `https://eu.bisibility.com/api/v1`
- URL: `https://eu.bisibility.com/api/v1/projects/{project_id}/keywords`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `/api/auth/oauth2/authorize`, token URL `/api/auth/oauth2/token`, scopes: `api:read`)

## Path parameters

- `project_id` string, required: Public project ID; membership and token scope are enforced.

## Query parameters

- `limit` integer
- `cursor` string
- `search` string
- `tag` string
- `topic` string
- `intent` string
- `device` 'desktop' | 'mobile'
- `location_key` string
- `country` string
- `position_gt` number
- `position_lt` number
- `sort` 'created_at' | '-created_at' | 'keyword' | '-keyword' | 'text' | '-text' | 'updated_at' | '-updated_at'
- `filter[country]` string
- `filter[device]` 'desktop' | 'mobile'
- `filter[intent]` string
- `filter[location_key]` string
- `filter[position_gt]` number
- `filter[position_lt]` number
- `filter[tag]` string
- `filter[topic]` string
- `q` string

## Headers

- `Bisibility-API-Version` 'v1'
- `X-Bisibility-Source` 'sdk' | 'cli' | 'mcp'

## Response `200`

JSON response

- object
  - `data` Keyword[], required
    - `country` string, required: Resolved keyword location display name.
    - `created_at` string, date-time, required
    - `device` 'desktop' | 'mobile', required
    - `id` string, required
    - `intent` string, nullable, required
    - `latest_check` KeywordLatestCheck, nullable, required: The most recent executed check of any status. A completed check with `position: null` can have unknown coverage; read `observation_completeness` before inferring absence within the requested depth; `latest_check.status: "failed"` means "unknown, the check did not run to completion".
      - `checked_at` string, date-time, required
      - `error` string, nullable, required
      - `error_code` string, nullable, required
      - `id` string, required
      - `observation_completeness` 'complete' | 'truncated_by_stop_on_match' | 'unknown' | 'null', nullable, required: Persisted coverage, or null when legacy metadata is absent. Only complete coverage supports absence within depth; a valid positive rank remains valid with truncated coverage.
      - `position` integer, nullable, required
      - `run_id` string, nullable, required: Rank-check run that produced this check, or null for a legacy row.
      - `status` 'completed' | 'failed' | 'running', required
    - `latest_position` integer, nullable, required: `latest_position` = `latest_check.position`; it is `null` for failed checks, unknown observation coverage, or absence within the requested depth. Agents that need "the last known ranking" must read `latest_successful_check.position`.
    - `latest_successful_check` KeywordLatestSuccessfulCheck, nullable, required: The most recent completed check. Null position with unknown observation_completeness does not establish absence within depth.
      - `checked_at` string, date-time, required
      - `id` string, required
      - `observation_completeness` 'complete' | 'truncated_by_stop_on_match' | 'unknown' | 'null', nullable, required: Persisted coverage, or null when legacy metadata is absent. Only complete coverage supports absence within depth; a valid positive rank remains valid with truncated coverage.
      - `position` integer, nullable, required
      - `ranking_url` string, nullable, required
      - `run_id` string, nullable, required: Rank-check run that produced this check, or null for a legacy row.
    - `language_code` string, required
    - `language_label` string, required
    - `location` string, required: Resolved keyword location display name.
    - `location_key` string, required: Canonical country, region, or city key, optionally qualified with @language. The default language normalizes to the unqualified key.
    - `previous_position` integer, nullable, required: `previous_position` = the position recorded on `latest_check` as its predecessor.
    - `project_id` string, required
    - `ranking_url` string, nullable, required
    - `schedule` object, nullable, required
      - `cron_expression` string, nullable, required
      - `frequency` 'paused' | 'manual' | 'daily' | 'weekly' | 'monthly' | 'custom_cron', required
      - `jitter_minutes` integer, required: Whole-minute random delay from 0 to 120. Set 0 to disable jitter.
      - `last_checked_at` string, date-time, nullable, required
      - `next_check_at` string, date-time, nullable, required
      - `source` 'keyword' | 'project_default', required: Whether these schedule values come from the keyword's own row or from the project defaults.
      - `timezone` string, required: IANA time zone that anchors monthly and custom cron wall-clock schedules. Daily and weekly use a stable keyword-specific interval phase that timezone does not move.
    - `tags` string[], required
    - `target_url` string, nullable, required
    - `text` string, required
    - `topic` string, nullable, required
    - `updated_at` string, date-time, required
  - `meta` object, required
    - `next_cursor` string, nullable, required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Unsupported API version
- `429`: Rate limited

## Changes

- **2026-10-19** `a6e1ec0dec82`: 1 breaking, 15 info
  - added the new path request parameter `project_id`
  - the endpoint scheme security `AppOAuth` was added to the API
  - added the new optional `query` request parameter `filter[country]`
  - added the new optional `query` request parameter `filter[device]`
  - …12 more

[Operation history](https://skmtc.dev/bisibility/apis/bisibility-public-api/changes/projects/:project_id/keywords/get.md)

---

[API](https://skmtc.dev/bisibility/apis/bisibility-public-api.md) · [All operations](https://skmtc.dev/bisibility/apis/bisibility-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bisibility/apis/bisibility-public-api/revisions/a6e1ec0dec82?raw)