---
title: "Search issues"
method: POST
path: "/v1/issues/search"
tags: ["Issues"]
---

# Search issues

`POST /v1/issues/search`

## Request

- Base URL: `https://docs.grepr.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.grepr.ai/v1/issues/search`
- Auth: one of:
  - API key in header `GREPR-API-KEY`
  - OpenID Connect (`https://grepr-prod.us.auth0.com/.well-known/openid-configuration`)

Returns the issues matching every given filter, ranked by full-text relevance when a query is given and by latest sighting otherwise. By default, open issues plus those closed in the last 30 days.

## Request body

- SearchIssuesRequest: Filters for searching the issues the caller can see. Every filter is optional; all given filters must match. Results are ordered by full-text rank when `query` is given, else by latest sighting.
  - `assignee` IssueAssigneeFilter: Whose active assignments a search matches. A deleted agent's assignment never counts, as it does not block a close.
    - `id` string: The agent's or person's id, for `AGENT` and `PERSON` only.
    - `kind` 'ME' | 'UNASSIGNED' | 'AGENT' | 'PERSON', required: `ME` for the caller, `UNASSIGNED` for issues nobody is working on, or `AGENT`/`PERSON` for one assignee.
  - `closedWithinDays` integer: Include closed issues closed within this many days. Absent: 30 when `states` is absent, with those closed as IGNORED or NOT_A_PROBLEM kept at any age, and no window when it is given. Given, it's exact.
  - `cursor` string: The `nextCursor` of the previous page, sent with the same filters.
  - `entities` object: Entity tags to match: every key must match, and any of a key's values matches it. Keys and values match in any case. An unprefixed key is put in the `entity:` namespace.
  - `fingerprint` string: Only issues with exactly this fingerprint.
  - `labels` string[]: Only issues carrying every one of these labels.
  - `limit` integer: The page size, at most 100; absent: 25.
  - `linkedTo` IssueLinkRef: A linked object to find issues by, such as a pipeline or an investigation.
    - `kind` 'PIPELINE' | 'INVESTIGATION' | 'MEMORY' | 'AGENT_SUGGESTION' | 'EXTERNAL' | 'ISSUE', required: What the object is.
    - `target` string, required: Its id, or the URL for an external link.
  - `priority` 'P0' | 'P1' | 'P2' | 'P3': Only issues at this priority or more urgent.
  - `query` string: Words to search the whole issue for, comments included, split and stemmed as the issue is, so checkout-api is also checkout and api: an issue matches when it has any one of them, and those with the most, above all in their title, fingerprint and entities, come first.
  - `states` string[]: Only issues in these states. Absent: open issues plus those closed within `closedWithinDays`, and, when that is absent too, those closed as IGNORED or NOT_A_PROBLEM at any age.
  - `teamIds` string[]: Only issues one of these teams can see: linked to one of them, or shared with all teams.
  - `updatedSince` string, date-time: Only issues changed at or after this time.

## Response `200`

Search results

- SearchIssuesResponse: A page of search results. Paging is best effort on a live board: an issue that changes between pages can move.
  - `items` IssueSummary[]: The matching issues on this page.
    - `assignees` IssueAssigneeRef[]: Who is working on it, oldest first: active assignments, without a deleted agent's.
      - `id` string: The person's id, or the agent's.
      - `kind` 'PERSON' | 'AGENT': A person or an agent.
    - `commentCount` integer: How many comments it has, guidance included.
    - `confidence` 'CONFIRMED' | 'LIKELY' | 'UNVERIFIED': How sure the reporter is that the problem is real.
    - `duplicateOf` string: The surviving issue, for a duplicate; null when the reader can't see it.
    - `duplicateOfHidden` boolean: True when the reader can't see the surviving issue.
    - `entities` object: The `entity:*` tags it concerns.
    - `expiresAt` string, date-time: When it stops applying and closes, or null.
    - `guidanceCount` integer: How many of its comments are guidance from people.
    - `id` string: The issue id.
    - `labels` string[]: Its categories.
    - `lastSeenAt` string, date-time: The latest sighting, or when it was filed.
    - `locked` boolean: Whether people have locked any field or label against agent changes.
    - `nextStep` string: The concrete next action, or null.
    - `number` integer: The short per-organization handle.
    - `occurrenceCount` integer: How many investigations sighted it.
    - `pipelineIds` string[]: The pipelines it concerns: its pipeline links' targets, then its `entity:pipeline`, without repeats.
    - `priority` 'P0' | 'P1' | 'P2' | 'P3': How soon someone should act.
    - `regressed` boolean: Whether it reopened after being fixed.
    - `resolution` 'FIXED' | 'DUPLICATE' | 'NOT_A_PROBLEM' | 'IGNORED' | 'OBSOLETE' | 'EXPIRED': Why it closed, or null while open.
    - `revisitAt` string, date-time: When someone should check back, or null.
    - `runs` IssueRun[]: Its runs that haven't ended, oldest first: queued or working on it, handed, picked up or watching.
      - `agentId` string: The run's agent.
      - `investigationId` string: The run's investigation id.
      - `status` 'QUEUED' | 'RUNNING' | 'STOPPING' | 'CANCELLING' | 'STOPPED' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'DISCARDED': Where the run is: QUEUED, RUNNING, STOPPING, CANCELLING, or STOPPED and resumable.
    - `state` 'TRIAGE' | 'READY' | 'IN_PROGRESS' | 'WAITING' | 'MONITORING' | 'CLOSED': Where the issue is in its lifecycle.
    - `teamIds` string[]: The teams that may see it.
    - `title` string: One line naming the problem.
    - `updatedAt` string, date-time: When it last changed.
    - `version` integer: Its current version, for a follow-up update.
    - `watchedBy` string: The agent watching it in Monitoring, or null.
  - `labelsInUse` string[]: The labels most used on recent issues the caller can see, so a new issue reuses them; on the first page only, null after.
  - `nextCursor` string: Pass back as `cursor`, with the same filters, for the next page; null on the last page.
  - `truncated` boolean: Whether the search stopped after 500 rows; refine the filters to see the rest.

## Other responses

- `400`: Invalid filters, or a cursor from another search
- `401`: Unauthorized
- `403`: No permission to view issues

---

[API](https://skmtc.dev/grepr/apis/grepr-api.md) - [All operations](https://skmtc.dev/grepr/apis/grepr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/grepr/apis/grepr-api/revisions/2a5ce03a0bf0?raw)