---
title: "Request research"
method: POST
path: "/v1/research-requests"
---

# Request research

`POST /v1/research-requests`

## Request

- Base URL: `https://api.ploti.ai`
- URL: `https://api.ploti.ai/v1/research-requests`
- Auth: HTTP bearer

File a research request: Ploti answers the user's question end to end when it needs data Ploti does not have. Ploti first checks which data the question needs (minutes), searching the web for sources, and reports what it already has and what is missing; when the check reports, Ploti files the missing pieces as data requests itself, which uses the workspace's research credits as the data is delivered. Its agents get the data, and when it arrives Ploti runs the research and emails the user the answer. Use it whenever the user needs data Ploti does not have, whether or not you know where it is published. Write the brief as the user would to an analyst: the question, the place, and what a good answer looks like; never the user's private parcels, owners or addresses unless the user asks for them to be researched. Creating the request and its data check costs nothing. Follow it with get_research_request.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `title` string, required: The name the user sees for the question in Ploti's list of research requests, e.g. 'Vacant industrial land near the Tampa port'.
  - `brief` string, required: The question, the place it is about, and what a good answer looks like.
  - `sources` object[]: Pages the user already knows are relevant, if any.
    - `url` string, uri, required: A page the user already knows bears on the question, such as a county GIS portal or an ordinance.
    - `details` string: What on that page matters to the question, when the link alone would not say.

## Response `201`

Created

- object
  - `request` object, required
    - `id` string, required
    - `title` string, required
    - `status` 'checking' | 'needs_answer' | 'report_ready' | 'data_requested' | 'researching' | 'complete', required
    - `statusText` string, required
    - `links` object, required
      - `view` string, required
  - `checkStarted` boolean, required

## Other responses

- `401`: The credential is missing or not valid.
- `413`: payload_too_large: the body is over 256 KB (2 MB for /v1/tools).
- `415`: unsupported_media_type: a body was sent without Content-Type: application/json.
- `429`: rate_limited: this credential is over its rate. Retry after the Retry-After header's seconds.
- `500`: internal: Ploti failed. Retry; if it keeps happening, contact support.
- `default`: Refused: nothing was done. The code says why and the links say where the person acts on it.

---

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