---
title: "Create Brief"
method: POST
path: "/api/v2/briefs"
tags: ["Briefs"]
---

# Create Brief

`POST /api/v2/briefs`

Create and kick off a Monitoring Brief. Returns **202 immediately** — a Brief takes ~5–10 minutes; poll `GET /api/v2/briefs/{id}` for status and content. Requires a plan with Briefs access; metered separately from query units.

## Request body

- object
  - `scope_text` string, required — One or two plain sentences: the situation, where it is, who/what is affected, and the decision it informs.
  - `time_window` '6h' | '24h' | '72h' | '7d' | '30d' — Recent window the Brief analyses.
  - `baseline_window` '7d' | '14d' | '30d' — Earlier comparison window for change detection.
  - `audience` 'executive' | 'analyst' | 'operator'
  - `depth` 'skim' | 'standard' | 'detailed'
  - `countries` string[] — ISO-3 country codes to scope the Brief.
  - `regions` string[]
  - `sectors` string[]
  - `search_topics` string[] — Free-text focus terms/phrases that bias retrieval.
  - `actors` string[] — Named actors to emphasize.
  - `entities` string[] — Named people or organizations to emphasize.
  - `locations` string[] — Plain-English sub-country locations.
  - `assets` string[] — Named facilities or infrastructure.
  - `public_link` boolean — When true, also mint a public shareable report URL.
  - `title` string — Optional; auto-generated from scope_text when omitted.
  - `brief_type` 'monitoring_brief' — Optional; defaults to monitoring_brief, the only generally-available type.

## Response `202`

Brief generation started.

- object
  - `id` string
  - `status` string
  - `brief_type` string
  - `title` string
  - `created_at` string
  - `web_url` string
  - `public_url` string, nullable
  - `message` string

## Other responses

- `401` — Missing or invalid API key.
- `403` — Briefs are not available on your plan (`BRIEF_ACCESS_DENIED`), or the included Brief allotment is exhausted (`BRIEF_LIMIT_REACHED`).

---

[API](https://skmtc.net/gdeltcloud/apis/gdelt-cloud-api-v2.md) · [All operations](https://skmtc.net/gdeltcloud/apis/gdelt-cloud-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gdeltcloud/gdelt-cloud-api-v2/revisions/01aaa6255180/schema)