buzzabout docsPattern detections
Kick off and poll cross-mention pattern discovery against a dataset.
A pattern detection is a one-shot async analysis of a dataset
that surfaces recurring narratives, hooks, or angles across many
mentions. The output is a Pattern — a
clustered set of PatternItems, each grouping the underlying posts
that exemplify it.
Pricing
Pattern detection charges 0.5 credits per post_processing — one
charge per post analysed, no reservation. See
Pricing.
Endpoints
Authorization
ApiKeyAuth 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
application/json
application/json
curl -X POST "https://example.com/v1/pattern_detections" \ -H "Content-Type: application/json" \ -d '{ "dataset_id": "ds_2NK4Y3JxhJ8r9c0Y1u5lkjm9Wb1", "name": "Pricing complaints", "research_question": "What recurring complaints come up about pricing?" }'{
"status": "info",
"data": {
"created_at": 1717200000,
"dataset_id": "ds_2NK4Y3JxhJ8r9c0Y1u5lkjm9Wb1",
"name": "Pricing complaints",
"research_question": "What recurring complaints come up about pricing?",
"run_id": "pdr_2NK4Z",
"status": {
"steps": [],
"type": "pending"
}
}
}{
"status": "info",
"error_code": "insufficient_credits_pattern_detection",
"detail": "string",
"transient": true
}{
"status": "info",
"error_code": "dataset_not_found",
"detail": "string",
"transient": true
}{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}Authorization
ApiKeyAuth Buzzabout API key, beginning with bz_live_ (or bz_test_ for staging-only keys).
In: header
Path Parameters
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/pattern_detections/string"{
"status": "info",
"data": {
"created_at": 1717200000,
"dataset_id": "ds_2NK4Y3JxhJ8r9c0Y1u5lkjm9Wb1",
"name": "Pricing complaints",
"research_question": "What recurring complaints come up about pricing?",
"run_id": "pdr_2NK4Z",
"status": {
"steps": [],
"type": "pending"
}
}
}{
"status": "info",
"error_code": "pattern_detection_run_not_found",
"detail": "string",
"transient": true
}{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}Lifecycle
POST /v1/pattern_detections returns immediately:
{
"status": "success",
"data": {
"run_id": "pdr_01H...",
"status": "pending"
}
}Poll GET /v1/pattern_detections/{run_id} until status is
completed. The completed response includes a pattern_id:
{
"run_id": "pdr_01H...",
"status": "completed",
"pattern_id": "pt_01H..."
}Resolve the pattern via
GET /v1/patterns/{pattern_id}.
Insufficient credits
Like other chargeable endpoints, returns 402 insufficient_credits if
the account doesn't have enough credits to cover the projected cost
(0.5 × posts_in_dataset). No partial runs.
Next steps
- Patterns — read a discovered pattern.
- Tracking agents — repeat the same analysis on a schedule.
- Reference types — pattern detections show up
as
references[]entries in assistant turns.