---
title: "List briefs"
method: GET
path: "/briefs"
tags: ["Briefs"]
---

# List briefs

`GET /briefs`

## Request

- Base URL: `https://viral.app/api/v1`
- URL: `https://viral.app/api/v1/briefs`
- Auth: API key in header `x-api-key`

Retrieves briefs with a plain-text excerpt (its variables marked as runs), their audience (everyone, or non-ended linked campaigns plus creators sent it directly), read progress at the current version, and sample video counts.

## Query parameters

- `search` string: Search by brief name
- `campaignIds` string[]: Filter briefs by campaigns they are linked to
- `page` number: Page number (1-based index)
- `perPage` number: Number of items per page (1-100)
- `sortCol` string: Sort column
- `sortDir` 'asc' | 'desc': Sort direction

## Response `200`

OK

- object: Paginated list of briefs with their audience, read progress and sample counts
  - `data` object[], required
    - `id` string, required: Campaign brief ID with orgbrief_ prefix
    - `name` string, required
    - `excerpt` object[], required
      - `kind` 'heading' | 'paragraph' | 'item', required
      - `runs` object[], required
        - `type` 'text' | 'variable', required
        - `text` string, required
    - `campaigns` object[], required
      - `id` string, required: Campaign ID with orgcamp_ prefix
      - `name` string, required
      - `status` 'upcoming' | 'active' | 'closing' | 'ended', required: Campaign lifecycle status derived from validity window. upcoming: validFrom in the future; active: started with no end date; closing: started and has an end date in the present/future; ended: end date is in the past.
      - `activeCreatorCount` integer, required
    - `audience` object, required
      - `allCreators` boolean, required
      - `campaigns` object[], required
        - `id` string, required: Campaign ID with orgcamp_ prefix
        - `name` string, required
        - `status` 'upcoming' | 'active' | 'closing' | 'ended', required: Campaign lifecycle status derived from validity window. upcoming: validFrom in the future; active: started with no end date; closing: started and has an end date in the present/future; ended: end date is in the past.
        - `activeCreatorCount` integer, required
      - `creators` object[], required
        - `id` string, required: Organization creator ID with orgcre_ prefix
        - `name` string, nullable, required
        - `image` string, nullable, required
      - `creatorCount` integer, required
      - `creatorIds` string[], required
    - `readCounts` object, required
      - `read` integer, required
      - `total` integer, required
    - `sampleVideoCount` integer, required
    - `notifiableCreatorCount` integer, required
    - `updatedAt` string, date-time, required
  - `pageCount` number, required: Total number of pages
  - `totalRows` number, required: Total number of rows

## Other responses

- `400`: 400
- `401`: 401
- `402`: 402
- `404`: 404
- `408`: 408
- `429`: 429
- `500`: 500

---

[API](https://skmtc.dev/viral/apis/viral-app-api.md) · [All operations](https://skmtc.dev/viral/apis/viral-app-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viral/apis/viral-app-api/revisions/31e97fa79ef1?raw)