buzzabout docs
API referenceEndpoints

Audience datasets

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

An audience dataset turns the posts in a source dataset into a collection of typed audience profiles (age range, role, interests, inferred persona). Profile collection is asynchronous, like a regular dataset run.

Pricing

Audience-dataset runs charge 3 credits per audience_profile, reservation-based. The reservation is sized by total_profile_count (default 850) and refunded down to actuals on completion. See Pricing.

Endpoints

POST
/v1/audience_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/audience_datasets" \  -H "Content-Type: application/json" \  -d '{    "name": "Hair-loss Q2 audience"  }'
{
  "status": "info",
  "data": {
    "created_at": "2026-05-01T10:14:22Z",
    "id": "ad_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "name": "Hair-loss Q2 audience"
  }
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET
/v1/audience_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/audience_datasets"
{
  "status": "info",
  "data": [
    {
      "created_at": "2026-05-01T10:14:22Z",
      "id": "ad_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
      "name": "Hair-loss Q2 audience",
      "profile_count": 850,
      "updated_at": "2026-05-01T11:42:08Z"
    }
  ],
  "has_next": true,
  "cursor": "string"
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET
/v1/audience_datasets/{audience_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

audience_dataset_id*Audience Dataset Id

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/audience_datasets/string"
{
  "status": "info",
  "data": {
    "created_at": "2026-05-01T10:14:22Z",
    "id": "ad_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "name": "Hair-loss Q2 audience",
    "profile_count": 850,
    "updated_at": "2026-05-01T11:42:08Z"
  }
}
{
  "status": "info",
  "error_code": "audience_dataset_not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
PATCH
/v1/audience_datasets/{audience_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

audience_dataset_id*Audience 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/audience_datasets/string" \  -H "Content-Type: application/json" \  -d '{    "name": "Hair-loss Q2 audience (renamed)"  }'
{
  "status": "info",
  "data": {
    "created_at": "2026-05-01T10:14:22Z",
    "id": "ad_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "name": "Hair-loss Q2 audience",
    "profile_count": 850,
    "updated_at": "2026-05-01T11:42:08Z"
  }
}
{
  "status": "info",
  "error_code": "audience_dataset_not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
DELETE
/v1/audience_datasets/{audience_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

audience_dataset_id*Audience Dataset Id

Response Body

application/json

application/json

curl -X DELETE "https://example.com/v1/audience_datasets/string"
Empty
{
  "status": "info",
  "error_code": "audience_dataset_not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST
/v1/audience_datasets/{audience_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

audience_dataset_id*Audience 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

application/json

application/json

curl -X POST "https://example.com/v1/audience_datasets/string/runs" \  -H "Content-Type: application/json" \  -d '{    "source_dataset_id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",    "total_profile_count": 850  }'
{
  "status": "info",
  "data": {
    "audience_dataset_id": "ad_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "created_at": "2026-05-01T10:14:22Z",
    "id": "adr_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "source_dataset_id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "status": {
      "type": "in_progress"
    }
  }
}
{
  "status": "info",
  "error_code": "source_dataset_has_no_completed_run",
  "detail": "string",
  "transient": true
}
{
  "status": "info",
  "error_code": "insufficient_credits_audience_dataset_run",
  "detail": "string",
  "transient": true
}
{
  "status": "info",
  "error_code": "audience_dataset_not_found",
  "detail": "string",
  "transient": true
}
{
  "status": "info",
  "error_code": "audience_dataset_run_already_in_flight",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET
/v1/audience_datasets/{audience_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

audience_dataset_id*Audience 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/audience_datasets/string/runs"
{
  "status": "info",
  "data": [
    {
      "audience_dataset_id": "ad_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
      "created_at": "2026-05-01T10:14:22Z",
      "id": "adr_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
      "profile_count": 850,
      "source_dataset_id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
      "status": {
        "type": "done"
      },
      "target_profile_count": 850,
      "updated_at": "2026-05-01T11:42:08Z"
    }
  ],
  "has_next": true,
  "cursor": "string"
}
{
  "status": "info",
  "error_code": "audience_dataset_not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET
/v1/audience_datasets/{audience_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

audience_dataset_id*Audience Dataset Id
run_id*Run Id

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/audience_datasets/string/runs/string"
{
  "status": "info",
  "data": {
    "audience_dataset_id": "ad_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "created_at": "2026-05-01T10:14:22Z",
    "id": "adr_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "profile_count": 850,
    "source_dataset_id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "status": {
      "type": "done"
    },
    "target_profile_count": 850,
    "updated_at": "2026-05-01T11:42:08Z"
  }
}
{
  "status": "info",
  "error_code": "audience_dataset_not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Source dataset

Every audience-dataset run takes a source_dataset_id pointing at an existing (completed) dataset. The audience pipeline reads that dataset's mentions and infers a profile per distinct author / handle.

total_profile_count (default 850, range 1–2000) bounds how many profiles the run will attempt to produce. The run stops early if the source dataset doesn't have that many distinct authors.

Read collected profiles

Once a run reaches completed, query POST /v1/audience_profiles with the audience dataset's id to read what the run produced.

Next steps

Datasets

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

Tracking agents

Nine endpoints — manage agents that re-scrape on a schedule, watch for narrative shifts, and emit alerts.

On this page

EndpointsSource datasetRead collected profilesNext steps