---
title: "Query known failure patterns"
method: POST
path: "/api/pitfalldb/query"
tags: ["PitfallDB"]
---

# Query known failure patterns

`POST /api/pitfalldb/query`

## Request

- Base URL: `https://plith.ai`
- URL: `https://plith.ai/api/pitfalldb/query`
- Auth: none required

Returns known agent failure patterns for a task type. Pipeline: exact task_type match (SQL) → optional semantic embedding search if task_description is provided. Only returns pitfalls meeting visibility threshold (verified_report_count >= 1 OR report_count >= 3). Sorted by severity then report_count. Costs 2 credits.

## Request body

- object
  - `task_type` string, required: Required. Task category to query pitfalls for.
  - `task_description` string: Optional. If provided, triggers a semantic embedding search in addition to exact match.
  - `filters` object: Optional. Filter results by applies_to metadata.
    - `language` string
    - `framework` string
    - `provider` string

## Response `200`

Matching pitfalls

- object
  - `pitfalls` object[]
    - `id` string: Prefixed short ID (pit_ + 8 chars).
    - `severity` 'low' | 'medium' | 'high' | 'critical'
    - `title` string
    - `description` string
    - `frequency` string: Human-readable frequency estimate, e.g. '73% of attempts affected (42 reports)'.
    - `reports` integer: Total number of reports for this pitfall.
    - `fix` string, nullable
    - `fix_confidence` number: 0–1 confidence in the fix.
    - `tags` string[]
    - `applies_to` object: Language/framework/provider applicability metadata.
  - `total_matching` integer
  - `cross_product` string
  - `request_id` string
  - `credits_used` integer
  - `credits_remaining` integer
  - `fallback_behavior` string

## Other responses

- `400`: Missing task_type
- `401`: Invalid or missing API key
- `402`: Insufficient credits
- `413`: Payload too large

---

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