Agentic Platform
Documentation API reference Tools Skills

Tools

List Annotations

list_annotations MCP Web search

Retrieve annotations logged on your project.

Playground

POST
item
period_start

Optional inclusive start of the period filter (ISO date, e.g. 2024-01-01). Annotations whose start_date falls within this period are returned.

period_end

Optional inclusive end of the period filter (ISO date, e.g. 2024-12-31). Annotations whose start_date falls within this period are returned.

Credits

Fixed cost per item requested. This tool reads data Botify already holds for your project and calls no outside service, so nothing is added to the per-call price.

These usage SKUs can be charged on a call.

SKU Credits Description
Tool call 1 per request Charged once per successful item.

Schemas

item is what you send, config how the tool behaves, and the response is what you get back.

Item

object
Properties
period_start string | null

Optional inclusive start of the period filter (ISO date, e.g. 2024-01-01). Annotations whose start_date falls within this period are returned.

Default: null

period_end string | null

Optional inclusive end of the period filter (ISO date, e.g. 2024-12-31). Annotations whose start_date falls within this period are returned.

Default: null

Example
{
  "period_start": null,
  "period_end": null
}

Response

object
Properties
annotations array required

Project chart annotations for the project

Items: ChartAnnotation

count integer required

Number of annotations returned after filtering

total_count integer required

Total number of annotations on the project before filtering

Example
{
  "annotations": [
    {
      "start_date": "string",
      "data": null
    }
  ],
  "count": 0,
  "total_count": 0
}

Type Definitions

2 types

These are the available sub-object types that can be used in the properties above.

ChartAnnotation object
#

Project chart annotation with only the fields exposed by the agent.

start_date string (date-time) required

Annotation start date and time

data ChartAnnotationData

Annotation payload (typically includes content text)

Type: ChartAnnotationData

Default: null

ChartAnnotationData object
#
content string | null

Default: null

Endpoints

POST http://agents.botify.com/{organization}/{project}/list_annotations/process
POST http://agents.botify.com/{organization}/{project}/list_annotations/batch_process
POST http://agents.botify.com/{organization}/{project}/list_annotations/async_process
POST http://agents.botify.com/{organization}/{project}/list_annotations/async_batch_process

See running a long job in the background for the polling flow.

cURL

curl -X POST "http://agents.botify.com/{organization}/{project}/list_annotations/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {}
}'

Over MCP

This tool is exposed as the MCP tool list_annotations. An MCP client passes organization, project and item as tool arguments. Set up MCP →

Raw metadata