buzzabout docs
API referenceEndpoints

Tracking agents

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

A tracking agent is a long-running re-scrape + analysis schedule attached to a dataset. Each cycle re-pulls fresh mentions, looks for pattern drift, and emits messages summarising what changed.

Pricing

Each re-scrape cycle charges per-mention as a normal dataset run (mention category, reservation-based). Manual trigger calls follow the same model. See Pricing.

Endpoints

POST
/v1/tracking_agents

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

application/json

application/json

curl -X POST "https://example.com/v1/tracking_agents" \  -H "Content-Type: application/json" \  -d '{    "count": 50,    "dataset_ids": [      "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj"    ],    "instructions": "Surface posts complaining about Acme\'s pricing or contract terms.",    "integration_ids": [],    "name": "Daily Acme pricing scan",    "num_comments_per_post": 10,    "schedule": {      "frequency": "daily",      "time": "09:00"    }  }'
{
  "status": "info",
  "data": {
    "count": 50,
    "created_at": 1717200000,
    "dataset_ids": [
      "ds_abc"
    ],
    "id": "ta_2NK4Z",
    "instructions": "Track pricing complaints mentioning Acme",
    "integrations": [],
    "last_run_at": 1717200000,
    "name": "Daily pricing scan",
    "next_run_at": 1717286400,
    "num_comments_per_post": 10,
    "paused": false,
    "schedule": {
      "frequency": "daily",
      "time": "09:00"
    },
    "updated_at": 1717200000
  }
}
{
  "status": "info",
  "error_code": "tracking_agent_limit_reached",
  "detail": "string",
  "transient": true
}
{
  "status": "info",
  "error_code": "not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET
/v1/tracking_agents

Authorization

ApiKeyAuth
x-api-key<token>

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

In: header

Response Body

application/json

curl -X GET "https://example.com/v1/tracking_agents"
{
  "status": "info",
  "data": [
    {
      "count": 50,
      "created_at": 1717200000,
      "dataset_ids": [
        "ds_abc"
      ],
      "id": "ta_2NK4Z",
      "instructions": "Track pricing complaints mentioning Acme",
      "integrations": [],
      "last_run_at": 1717200000,
      "name": "Daily pricing scan",
      "next_run_at": 1717286400,
      "num_comments_per_post": 10,
      "paused": false,
      "schedule": {
        "frequency": "daily",
        "time": "09:00"
      },
      "updated_at": 1717200000
    }
  ]
}
GET
/v1/tracking_agents/{agent_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

agent_id*Agent Id

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/tracking_agents/string"
{
  "status": "info",
  "data": {
    "count": 50,
    "created_at": 1717200000,
    "dataset_ids": [
      "ds_abc"
    ],
    "id": "ta_2NK4Z",
    "instructions": "Track pricing complaints mentioning Acme",
    "integrations": [],
    "last_run_at": 1717200000,
    "name": "Daily pricing scan",
    "next_run_at": 1717286400,
    "num_comments_per_post": 10,
    "paused": false,
    "schedule": {
      "frequency": "daily",
      "time": "09:00"
    },
    "updated_at": 1717200000
  }
}
{
  "status": "info",
  "error_code": "not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
PATCH
/v1/tracking_agents/{agent_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

agent_id*Agent 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/tracking_agents/string" \  -H "Content-Type: application/json" \  -d '{    "name": "Daily Acme pricing scan (refined)",    "schedule": {      "day": "mon",      "frequency": "weekly",      "time": "09:00"    }  }'
{
  "status": "info",
  "data": {
    "count": 50,
    "created_at": 1717200000,
    "dataset_ids": [
      "ds_abc"
    ],
    "id": "ta_2NK4Z",
    "instructions": "Track pricing complaints mentioning Acme",
    "integrations": [],
    "last_run_at": 1717200000,
    "name": "Daily pricing scan",
    "next_run_at": 1717286400,
    "num_comments_per_post": 10,
    "paused": false,
    "schedule": {
      "frequency": "daily",
      "time": "09:00"
    },
    "updated_at": 1717200000
  }
}
Empty
{
  "status": "info",
  "error_code": "not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
DELETE
/v1/tracking_agents/{agent_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

agent_id*Agent Id

Response Body

application/json

application/json

curl -X DELETE "https://example.com/v1/tracking_agents/string"
Empty
{
  "status": "info",
  "error_code": "not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST
/v1/tracking_agents/{agent_id}/pause

Authorization

ApiKeyAuth
x-api-key<token>

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

In: header

Path Parameters

agent_id*Agent Id

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/tracking_agents/string/pause"
Empty
{
  "status": "info",
  "error_code": "not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST
/v1/tracking_agents/{agent_id}/resume

Authorization

ApiKeyAuth
x-api-key<token>

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

In: header

Path Parameters

agent_id*Agent Id

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/tracking_agents/string/resume"
Empty
{
  "status": "info",
  "error_code": "not_found",
  "detail": "string",
  "transient": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST
/v1/tracking_agents/{agent_id}/trigger

Authorization

ApiKeyAuth
x-api-key<token>

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

In: header

Path Parameters

agent_id*Agent Id

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/tracking_agents/string/trigger"
{
  "status": "info",
  "data": {
    "agent_id": "ta_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "created_at": 1746090862,
    "dataset_run_ids": [
      "dsr_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj"
    ],
    "id": "tar_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "status": {
      "type": "in_progress"
    }
  }
}
{
  "status": "info",
  "error_code": "insufficient_credits",
  "detail": "string",
  "transient": true
}
{
  "status": "info",
  "error_code": "not_found",
  "detail": "string",
  "transient": true
}
{
  "status": "info",
  "error_code": "tracking_agent_run_in_progress",
  "detail": "string",
  "transient": true
}
{
  "status": "info",
  "error_code": "dataset_has_no_queries",
  "detail": "string",
  "transient": true
}
GET
/v1/tracking_agents/{agent_id}/messages

Authorization

ApiKeyAuth
x-api-key<token>

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

In: header

Path Parameters

agent_id*Agent Id

Query Parameters

limit?Limit
Default25
Range1 <= value <= 100
cursor?|null

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/tracking_agents/string/messages"
{
  "status": "info",
  "data": [
    {
      "agent_id": "ta_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
      "agent_name": "Daily Acme pricing scan",
      "comment_count": 87,
      "created_at": 1746090862,
      "message_id": "tam_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
      "new_mention_count": 12,
      "sentiment_score": -0.41,
      "short_preview_message": "12 new posts; sentiment dipped after the Friday price-tier change"
    }
  ],
  "has_next": true,
  "cursor": "string"
}
{
  "status": "info",
  "error_code": "not_found",
  "detail": "string",
  "transient": true
}
{
  "status": "info",
  "error_code": "invalid_cursor",
  "detail": "string",
  "transient": true
}

Lifecycle

An agent moves through three states:

  • active — re-scrapes on the configured schedule, emits messages for noteworthy changes.
  • paused — no scheduled work; POST .../resume brings it back online without losing history.
  • deleted — soft delete. The agent and its message history are hidden from list endpoints but retained on the server.

POST .../trigger forces an out-of-schedule cycle. It returns 402 if the account has insufficient credits to cover the reservation.

Messages

GET .../{id}/messages returns the per-agent alert feed, cursor-paginated, newest first. Each message has a text body (markdown with inline post links — see Reference types) plus a created_at timestamp.

Pattern-detection alerts include a pattern reference under references[]; expand via GET /v1/patterns/{id}.

Next steps

Audience datasets

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

Mentions

POST /v1/mentions — global, filterable, paginated mentions across one or more datasets.

On this page

EndpointsLifecycleMessagesNext steps