buzzabout docs
API referenceEndpoints

Datasets

Eight endpoints — full CRUD on dataset containers plus async scraping runs.

A dataset is a named container of mentions. Runs populate it with posts collected across one or more search queries. Resources are scoped to the account that owns the API key.

Pricing

Dataset runs charge 1 credit per mention collected, reservation-based — any unused reservation is refunded on completion. See Pricing.

Endpoints

POST
/v1/datasets

Authorization

ApiKeyAuth
x-api-key<token>

Buzzabout API key, beginning with bz_live_ (or bz_test_ for staging-only keys).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/datasets" \  -H "Content-Type: application/json" \  -d '{    "name": "Hair-loss conversations Q2"  }'
{
  "status": "info",
  "data": {
    "created_at": "2026-05-01T10:14:22Z",
    "id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "name": "Hair-loss conversations Q2"
  }
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET
/v1/datasets

Authorization

ApiKeyAuth
x-api-key<token>

Buzzabout API key, beginning with bz_live_ (or bz_test_ for staging-only keys).

In: header

Query Parameters

limit?Limit
Default10
Range1 <= value <= 100
cursor?|null
order?Order
Default"desc"
Value in"asc" | "desc"

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/datasets"
{
  "status": "info",
  "data": [
    {
      "created_at": "2026-05-01T10:14:22Z",
      "id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
      "mentions_count": 187,
      "name": "Hair-loss conversations Q2",
      "updated_at": "2026-05-01T10:31:08Z",
      "url": "https://app.buzzabout.ai/research/ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj"
    }
  ],
  "has_next": true,
  "cursor": "string"
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET
/v1/datasets/{dataset_id}

Authorization

ApiKeyAuth
x-api-key<token>

Buzzabout API key, beginning with bz_live_ (or bz_test_ for staging-only keys).

In: header

Path Parameters

dataset_id*Dataset Id

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/datasets/string"
{
  "status": "info",
  "data": {
    "created_at": "2026-05-01T10:14:22Z",
    "id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "mentions_count": 187,
    "name": "Hair-loss conversations Q2",
    "updated_at": "2026-05-01T10:31:08Z",
    "url": "https://app.buzzabout.ai/research/ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj"
  }
}
{
  "status": "info",
  "error_code": "dataset_not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
PATCH
/v1/datasets/{dataset_id}

Authorization

ApiKeyAuth
x-api-key<token>

Buzzabout API key, beginning with bz_live_ (or bz_test_ for staging-only keys).

In: header

Path Parameters

dataset_id*Dataset Id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/datasets/string" \  -H "Content-Type: application/json" \  -d '{    "name": "Hair-loss conversations Q2 (renamed)"  }'
{
  "status": "info",
  "data": {
    "created_at": "2026-05-01T10:14:22Z",
    "id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "mentions_count": 187,
    "name": "Hair-loss conversations Q2",
    "updated_at": "2026-05-01T10:31:08Z",
    "url": "https://app.buzzabout.ai/research/ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj"
  }
}
{
  "status": "info",
  "error_code": "dataset_not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
DELETE
/v1/datasets/{dataset_id}

Authorization

ApiKeyAuth
x-api-key<token>

Buzzabout API key, beginning with bz_live_ (or bz_test_ for staging-only keys).

In: header

Path Parameters

dataset_id*Dataset Id

Response Body

application/json

application/json

curl -X DELETE "https://example.com/v1/datasets/string"
Empty
{
  "status": "info",
  "error_code": "dataset_not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST
/v1/datasets/{dataset_id}/runs

Authorization

ApiKeyAuth
x-api-key<token>

Buzzabout API key, beginning with bz_live_ (or bz_test_ for staging-only keys).

In: header

Path Parameters

dataset_id*Dataset Id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/datasets/string/runs" \  -H "Content-Type: application/json" \  -d '{    "content_analysis_actions": [],    "count": 200,    "country_code": "US",    "date_range": {      "from": "2026-04-01",      "to": "2026-04-30"    },    "enable_transcribing": false,    "enable_visual_recognition": false,    "language": "en",    "num_comments_per_post": 10,    "search_query": {      "fragments": [        "minoxidil",        "finasteride"      ],      "search_query": "people switching from minoxidil to finasteride",      "sources": [        "reddit",        "tiktok"      ],      "type": "prompt"    }  }'
{
  "status": "info",
  "data": {
    "created_at": "2026-05-01T10:14:22Z",
    "dataset_id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "id": "dsr_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "status": {
      "type": "in_progress"
    }
  }
}
{
  "status": "info",
  "error_code": "insufficient_credits_dataset_run",
  "detail": "string",
  "transient": true
}
{
  "status": "info",
  "error_code": "dataset_not_found",
  "detail": "string",
  "transient": true
}
{
  "status": "info",
  "error_code": "date_filter_unavailable",
  "detail": "string",
  "transient": true
}
GET
/v1/datasets/{dataset_id}/runs

Authorization

ApiKeyAuth
x-api-key<token>

Buzzabout API key, beginning with bz_live_ (or bz_test_ for staging-only keys).

In: header

Path Parameters

dataset_id*Dataset Id

Query Parameters

limit?Limit
Default10
Range1 <= value <= 100
cursor?|null
order?Order
Default"desc"
Value in"asc" | "desc"

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/datasets/string/runs"
{
  "status": "info",
  "data": [
    {
      "created_at": "2026-05-01T10:14:22Z",
      "dataset_id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
      "id": "dsr_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
      "mentions_count": 187,
      "new_mentions_count": 187,
      "params": {
        "content_analysis_actions": [],
        "count": 200,
        "country_code": "US",
        "date_range": {
          "from": "2026-04-01",
          "to": "2026-04-30"
        },
        "enable_transcribing": false,
        "enable_visual_recognition": false,
        "language": "en",
        "num_comments_per_post": 10,
        "search_query": {
          "search_query": "minoxidil vs finasteride",
          "sources": [
            "reddit"
          ],
          "type": "prompt"
        }
      },
      "status": {
        "type": "done"
      },
      "updated_at": "2026-05-01T10:31:08Z"
    }
  ],
  "has_next": true,
  "cursor": "string"
}
{
  "status": "info",
  "error_code": "dataset_not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET
/v1/datasets/{dataset_id}/runs/{run_id}

Authorization

ApiKeyAuth
x-api-key<token>

Buzzabout API key, beginning with bz_live_ (or bz_test_ for staging-only keys).

In: header

Path Parameters

dataset_id*Dataset Id
run_id*Run Id

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/datasets/string/runs/string"
{
  "status": "info",
  "data": {
    "created_at": "2026-05-01T10:14:22Z",
    "dataset_id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "id": "dsr_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "mentions_count": 187,
    "new_mentions_count": 187,
    "params": {
      "content_analysis_actions": [],
      "count": 200,
      "country_code": "US",
      "date_range": {
        "from": "2026-04-01",
        "to": "2026-04-30"
      },
      "enable_transcribing": false,
      "enable_visual_recognition": false,
      "language": "en",
      "num_comments_per_post": 10,
      "search_query": {
        "search_query": "minoxidil vs finasteride",
        "sources": [
          "reddit"
        ],
        "type": "prompt"
      }
    },
    "status": {
      "type": "done"
    },
    "updated_at": "2026-05-01T10:31:08Z"
  }
}
{
  "status": "info",
  "error_code": "dataset_not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Search queries

POST /v1/datasets/{id}/runs accepts a tagged-union search_query:

  • { "type": "prompt", "sources": [...], "search_query": "..." } — keyword search across one or more of reddit, tiktok, youtube, instagram, linkedin.
  • { "type": "url", "source_urls": [...] } — direct URL scraping; supports the same sources via URL pattern.

Both variants accept optional count, date_range, num_comments_per_post, country_code, language, enable_visual_recognition, enable_transcribing, and content_analysis_actions. See the schema above for exact bounds.

Run lifecycle

POST /v1/datasets/{id}/runs returns immediately with status: "pending". Poll GET /v1/datasets/{id}/runs/{run_id} until status.type is completed or failed. The status envelope reports each pipeline step (scraping, enrichment, analysis) with timestamps so you can render a progress UI.

When status.type === "failed", the full credit reservation is refunded. When completed, you are charged only for the mentions that were collected.

Read collected mentions

Once a run reaches completed, query POST /v1/mentions with the dataset's id to read what it collected. Mentions live across runs — re-running a dataset adds to the same pool.

Next steps

Reference types

How references[] and the post:source:id markdown scheme work across chats and the assistant.

Audience datasets

Audience datasets surface the people behind your mentions — eight endpoints, CRUD plus async profile-collection runs.

On this page

EndpointsSearch queriesRun lifecycleRead collected mentionsNext steps