---
title: "POST /api/projects/{project_id}/logs/natural_language_query/"
method: POST
path: "/api/projects/{project_id}/logs/natural_language_query/"
tags: ["logs"]
---

# POST /api/projects/{project_id}/logs/natural_language_query/

`POST /api/projects/{project_id}/logs/natural_language_query/`

## Request

- Base URL: `https://us.posthog.com`
- URL: `https://us.posthog.com/api/projects/{project_id}/logs/natural_language_query/`
- Auth: HTTP bearer

Turn a plain-language request into ranked log viewer filter candidates. Nothing is persisted. Only the request text, service names and attribute keys are sent to the models.

## Path parameters

- `project_id` string, required

## Request body

- LogsNaturalLanguageQueryRequest
  - `query` string, required: The plain-language request, for example 'error logs from checkout in the last 2 hours'.
  - `dateRange` LogsNaturalLanguageDateRange
    - `date_from` string, nullable: Start of the date range. Accepts ISO 8601 timestamps or relative formats such as -1h or -7d.
    - `date_to` string, nullable: End of the date range. Same format as date_from. Null means "now".

## Response `200`

- LogsNaturalLanguageQueryResponse
  - `candidates` LogsNaturalLanguageCandidate[], required: Readings of the request, best first. Can be empty.
    - `label` string, required: Short plain-language summary of this reading of the request.
    - `query` LogsNaturalLanguageCandidateQuery, required
      - `dateRange` LogsNaturalLanguageDateRange, required
        - `date_from` string, nullable: Start of the date range. Accepts ISO 8601 timestamps or relative formats such as -1h or -7d.
        - `date_to` string, nullable: End of the date range. Same format as date_from. Null means "now".
      - `severityLevels` SeverityLevelsEnum[], required: Severity levels to keep. Empty means all levels.
      - `serviceNames` string[], required: Services to keep. Empty means all services.
      - `filterGroup` LogsNaturalLanguageCandidateFilter[], required: Attribute and message filters, combined with AND.
        - `key` string, required: Attribute key, or "message" for the log body text.
        - `type` 'log' | 'log_attribute' | 'log_resource_attribute', required: * `log` - Log * `log_attribute` - Log Attribute * `log_resource_attribute` - Log Resource Attribute
        - `operator` string, required: Property operator, for example exact, icontains or is_set.
        - `value` unknown
    - `probability` number, double, nullable, required: How likely the decision model thinks this reading is. Null when not ranked.
  - `confidence` number, double, nullable, required: The first candidate's probability from the decision model. Null when it did not rank them.
  - `ranked_by` 'decision_model' | 'proposal_order', required: * `decision_model` - Decision Model * `proposal_order` - Proposal Order
  - `dropped_count` integer, required: Proposed readings dropped because they named a service or attribute key the project lacks.

## Other responses

- `502`
- `503`

## Changes

> 52 revisions in range; 1 not diffed.

- **2026-10-15** `98642c559af2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/posthog/apis/posthog-api/changes/api/projects/:project_id/logs/natural_language_query/post.md)

---

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