Custom parameters

Nine endpoints — define bespoke LLM-extracted fields, preview, and run them across a dataset.

A custom parameter is a named LLM extraction rule. Once defined, you point it at a dataset to populate the extracted value on every mention in that dataset. The shape and behaviour mirror the in-app "Custom data" surface.

Pricing

Custom-parameter runs charge 0.5 credits per post_processing — one charge per post the rule runs against. Previews are free. See Pricing.

Endpoints

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.

name*Name

Human-readable label for the parameter.

Length1 <= length <= 100

instructions*Instructions

Natural-language prompt the LLM applies to each mention when the parameter is run.

Length1 <= length

value_type*Value Type

Expected output type. string returns a single string per mention, list a list of strings, object an arbitrary JSON object.

Value in"string" | "list" | "object"

Response Body

`application/json`

curl -X POST "https://example.com/v1/custom_parameters" \  -H "Content-Type: application/json" \  -d '{    "instructions": "Classify the post\'s sentiment toward our brand as one of: positive, negative, neutral, mixed.",    "name": "Brand sentiment label",    "value_type": "string"  }'

{
  "status": "info",
  "data": {
    "created_at": 1746090862,
    "id": "cp_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "instructions": "Classify the post's sentiment toward our brand as one of: positive, negative, neutral, mixed.",
    "name": "Brand sentiment label",
    "updated_at": 1746091984,
    "value_type": "string"
  }
}

{
  "status": "info",
  "error_code": "custom_parameter_limit_exceeded",
  "detail": "string",
  "transient": true
}

{
  "status": "info",
  "error_code": "custom_parameter_duplicate_name",
  "detail": "string",
  "transient": true
}

{
  "status": "info",
  "error_code": "custom_parameter_empty_name",
  "detail": "string",
  "transient": true
}

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/custom_parameters"

{
  "status": "info",
  "data": [
    {
      "created_at": 1746090862,
      "id": "cp_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
      "instructions": "Classify the post's sentiment toward our brand as one of: positive, negative, neutral, mixed.",
      "name": "Brand sentiment label",
      "updated_at": 1746091984,
      "value_type": "string"
    }
  ]
}

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.

instructions*Instructions

Length1 <= length

value_type*Value Type

Value in"string" | "list" | "object"

post_refs*array<>

Items1 <= items <= 5

Response Body

`application/json`

curl -X POST "https://example.com/v1/custom_parameters/preview" \  -H "Content-Type: application/json" \  -d '{    "instructions": "Classify the post\'s sentiment toward our brand as one of: positive, negative, neutral, mixed.",    "post_refs": [      {        "id": "t3_1oqliu8",        "source": "reddit"      },      {        "id": "7396418572401016102",        "source": "tiktok"      }    ],    "value_type": "string"  }'

{
  "status": "info",
  "data": {
    "results": [
      {
        "post_id": "t3_1oqliu8",
        "source": "reddit",
        "value": "positive"
      },
      {
        "post_id": "7396418572401016102",
        "source": "tiktok",
        "value": "neutral"
      }
    ]
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Authorization

ApiKeyAuth

x-api-key<token>

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

In: header

Path Parameters

parameter_id*Parameter Id

Response Body

`application/json`

curl -X GET "https://example.com/v1/custom_parameters/string"

{
  "status": "info",
  "data": {
    "created_at": 1746090862,
    "id": "cp_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "instructions": "Classify the post's sentiment toward our brand as one of: positive, negative, neutral, mixed.",
    "name": "Brand sentiment label",
    "updated_at": 1746091984,
    "value_type": "string"
  }
}

{
  "status": "info",
  "error_code": "custom_parameter_not_found",
  "detail": "string",
  "transient": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Authorization

ApiKeyAuth

x-api-key<token>

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

In: header

Path Parameters

parameter_id*Parameter Id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?|null

instructions?|null

value_type?|null

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/custom_parameters/string" \  -H "Content-Type: application/json" \  -d '{    "name": "Brand sentiment label (refined)"  }'

{
  "status": "info",
  "data": {
    "created_at": 1746090862,
    "id": "cp_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "instructions": "Classify the post's sentiment toward our brand as one of: positive, negative, neutral, mixed.",
    "name": "Brand sentiment label",
    "updated_at": 1746091984,
    "value_type": "string"
  }
}

Empty

{
  "status": "info",
  "error_code": "custom_parameter_not_found",
  "detail": "string",
  "transient": true
}

{
  "status": "info",
  "error_code": "custom_parameter_duplicate_name",
  "detail": "string",
  "transient": true
}

{
  "status": "info",
  "error_code": "custom_parameter_empty_name",
  "detail": "string",
  "transient": true
}

Authorization

ApiKeyAuth

x-api-key<token>

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

In: header

Path Parameters

parameter_id*Parameter Id

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/custom_parameters/string"

Empty

{
  "status": "info",
  "error_code": "custom_parameter_not_found",
  "detail": "string",
  "transient": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Authorization

ApiKeyAuth

x-api-key<token>

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

In: header

Path Parameters

parameter_id*Parameter Id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

scope*

Run the parameter against every mention in the named dataset.

Wire shape is {"kind": "dataset", "id": "<dataset_id>"}. Kept as a tagged-union-style discriminator so a future view (or other) variant can be added without breaking the contract.

Response Body

`application/json`

curl -X POST "https://example.com/v1/custom_parameters/string/runs" \  -H "Content-Type: application/json" \  -d '{    "scope": {      "id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",      "kind": "dataset"    }  }'

{
  "status": "info",
  "data": {
    "run_id": "cpr_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj"
  }
}

{
  "status": "info",
  "error_code": "insufficient_credits_content_analysis",
  "detail": "string",
  "transient": true
}

{
  "status": "info",
  "error_code": "custom_parameter_not_found",
  "detail": "string",
  "transient": true
}

{
  "status": "info",
  "error_code": "custom_parameter_run_in_flight",
  "detail": "string",
  "transient": true
}

{
  "status": "info",
  "error_code": "nothing_to_analyze",
  "detail": "string",
  "transient": true
}

Authorization

ApiKeyAuth

x-api-key<token>

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

In: header

Path Parameters

parameter_id*Parameter Id

Response Body

`application/json`

curl -X GET "https://example.com/v1/custom_parameters/string/runs"

{
  "status": "info",
  "data": [
    {
      "created_at": 1746090862,
      "custom_parameter_id": "cp_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
      "id": "cpr_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
      "mentions_done": 124,
      "mentions_error": 2,
      "mentions_total": 187,
      "scope": {
        "id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
        "kind": "dataset"
      },
      "status": {
        "type": "processing"
      },
      "updated_at": 1746091984
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Authorization

ApiKeyAuth

x-api-key<token>

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

In: header

Path Parameters

parameter_id*Parameter Id

run_id*Run Id

Response Body

`application/json`

curl -X GET "https://example.com/v1/custom_parameters/string/runs/string"

{
  "status": "info",
  "data": {
    "created_at": 1746090862,
    "custom_parameter_id": "cp_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "id": "cpr_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
    "mentions_done": 124,
    "mentions_error": 2,
    "mentions_total": 187,
    "scope": {
      "id": "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj",
      "kind": "dataset"
    },
    "status": {
      "type": "processing"
    },
    "updated_at": 1746091984
  }
}

{
  "status": "info",
  "error_code": "custom_parameter_not_found",
  "detail": "string",
  "transient": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Preview before running

POST /v1/custom_parameters/preview takes raw instructions + value_type + 1–5 post_refs and returns the would-be extraction for those posts only. No charge. Use this loop to iterate on the prompt before committing to a full run.

Triggering a run

POST /v1/custom_parameters/{id}/runs takes a tagged-union scope:

{ "scope": { "kind": "dataset", "id": "ds_01H..." } }

dataset is the only variant in v1. The union shape keeps room for view or other scopes in a future revision without breaking the contract.

Run status

GET .../runs/{run_id} reports three counters:

mentions_total — posts the run will visit.
mentions_done — posts successfully processed.
mentions_error — posts the LLM couldn't process (retried; final failures appear here).

Use these to render a progress UI. The run is complete when mentions_done + mentions_error === mentions_total.

Reading extracted values

Once a run completes, query POST /v1/mentions with the parameter_ids field set to your parameter's id. Each mention's response includes the extracted value under custom_parameters[{parameter_id}].

Next steps

Mentions — read extracted values via parameter_ids.
Datasets — the scope target of a custom-parameter run.
Pattern detections — the sibling "process every post" analysis.

201application/json

402application/json

409application/json

422application/json

200application/json

200application/json

422application/json

200application/json

404application/json

422application/json

200application/json

204

404application/json

409application/json

422application/json

204

404application/json

422application/json

201application/json

402application/json

404application/json

409application/json

422application/json

200application/json

422application/json

200application/json

404application/json

422application/json

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`