Tools

Speedworkers Inventory

speedworkers_inventory MCP

Get the daily SpeedWorkers inventory of the project (pages in index, stale, expired, not indexed) and whether the rendering speed keeps up with it

Get the SpeedWorkers inventory of a project: how many pages are in each state, day by day, and whether the rendering capacity is enough to keep them fresh. The inventory is a daily snapshot of the pages SpeedWorkers knows about, counted by state: - in index: fresh pages, delivered - stale: past their refresh time but within their max stale time, still delivered while waiting to be re-rendered - expired: past their max stale time, no longer delivered - not indexed: in the inputs but never successfully rendered There is one row per day, broken down by the requested dimensions (by section by default): - section_name: SpeedWorkers section - config_id: SpeedWorkers config id - priority: refresh priority (emergency, high, medium or low) - refresh_frequency: refresh frequency of the pages, in minutes An empty list of dimensions returns one total per day. Rows can include up to 5 sample URLs per state. The crawl stats compare today's inventory to the max rendering speed of the production version: the required speed is what refreshing every page at its section refresh frequency needs, and a load above 1 means pages will go stale or expire. They are null when the inventory has never been computed, which is the case until the cache refresh is enabled on the production version. Use the speedworkers_config tool to see the sections and their refresh settings.

Playground

Organization Project

POST

item

date_start

Inclusive start of the inventory period (ISO date, e.g. 2026-09-01). Defaults to 29 days before date_end.

date_end

Inclusive end of the inventory period (ISO date, e.g. 2026-09-30). Defaults to today (UTC).

dimensions

Dimensions the daily inventory is broken down by, on top of the date (always included). Allowed values: 'section_name' (SpeedWorkers section), 'config_id' (SpeedWorkers config id), 'priority' (refresh priority: emergency, high, medium or low), 'refresh_frequency' (refresh frequency of the pages, in minutes). Each dimension added multiplies the number of rows. An empty list returns one total per day. Defaults to ['section_name'].

include_samples

Whether to return up to 5 sample URLs per page state (in index, stale, expired, not indexed) for each row

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

date_start string | null

Inclusive start of the inventory period (ISO date, e.g. 2026-09-01). Defaults to 29 days before date_end.

Default: null

date_end string | null

Inclusive end of the inventory period (ISO date, e.g. 2026-09-30). Defaults to today (UTC).

Default: null

dimensions array

Items: SpeedworkersInventoryDimension

Default: ["section_name"]

include_samples boolean

Whether to return up to 5 sample URLs per page state (in index, stale, expired, not indexed) for each row

Default: false

Example

{
  "date_start": null,
  "date_end": null,
  "dimensions": [
    "section_name"
  ],
  "include_samples": false
}

Type Definitions

1 type

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

SpeedworkersInventoryDimension string

Values: section_name config_id priority refresh_frequency

Response

object

Properties

date_start string (date) required

Inclusive start of the inventory period

date_end string (date) required

Inclusive end of the inventory period

inventory_stats array required

Daily inventory snapshots, one row per date and combination of dimension values, ordered by date. A day without a snapshot has no row. When truncated, a day only partly within the limit is left out, unless it is the only one.

Items: InventoryStatsRow

truncated boolean required

Whether the oldest days were left out to stay within 2000 rows: shorten the period or use fewer dimensions

crawl_stats CrawlStats required

Rendering capacity against today's inventory. Null when the inventory has never been computed for the website, i.e. the cache refresh is not enabled on the production version.

Type: CrawlStats

Example

{
  "date_start": "2024-01-01",
  "date_end": "2024-01-01",
  "inventory_stats": [
    {
      "date": "2024-01-01",
      "section_name": null,
      "config_id": null,
      "priority": null,
      "refresh_frequency": null,
      "count": 0,
      "count_in_index": 0,
      "count_in_stale": 0,
      "count_expired": 0,
      "count_not_indexed": 0,
      "samples_in_index": null,
      "samples_in_stale": null,
      "samples_expired": null,
      "samples_not_indexed": null
    }
  ],
  "truncated": true,
  "crawl_stats": {
    "max_speed": 0.0,
    "required_speed": 0.0,
    "max_pages_refresh": 0,
    "required_pages_refresh": 0,
    "pages_in_inventory": 0,
    "load": 0.0,
    "info": "success",
    "sections": [
      {
        "name": "string",
        "load": 0.0
      }
    ]
  }
}

Type Definitions

5 types

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

CrawlStats object

max_speed number | null required

Max rendering speed of the production version, in pages/s

required_speed number | null required

Rendering speed needed to refresh the whole inventory at the sections refresh frequencies, in pages/s

max_pages_refresh integer | null required

Pages that can be rendered per day at max speed

required_pages_refresh integer | null required

Pages that must be rendered per day to stay fresh

pages_in_inventory integer | null required

Pages in today's inventory

load number | null required

required_speed / max_speed: above 1, the website cannot refresh its inventory in time and pages go stale or expire

info CrawlStatsInfo required

success, or why the speeds could not be computed (no max speed, no pages in today's inventory, a section without refresh frequency...)

Type: CrawlStatsInfo

sections array required

Load of each delivered section

Items: CrawlStatsSection

CrawlStatsInfo string

Values: success no_config_js no_website_max_speed no_pages_in_inventory invalid_refresh_frequency

CrawlStatsSection object

name string required

SpeedWorkers section

load number | null required

Share of the website max speed this section requires

InventorySample object

url string required

Sample URL

device string | null required

Device the URL is cached for

InventoryStatsRow object

date string (date) required

Day of the inventory snapshot

section_name string | null

SpeedWorkers section (only with the section_name dimension)

Default: null

config_id string | null

SpeedWorkers config id (only with the config_id dimension)

Default: null

priority string | null

Refresh priority: emergency, high, medium or low (only with the priority dimension)

Default: null

refresh_frequency integer | null

Refresh frequency of the pages, in minutes (only with the refresh_frequency dimension)

Default: null

count integer required

Number of pages in the inventory

count_in_index integer required

Pages that are fresh and delivered by SpeedWorkers

count_in_stale integer required

Pages past their refresh time but within their max stale time: still delivered, waiting to be re-rendered

count_expired integer required

Pages past their max stale time: no longer delivered

count_not_indexed integer required

Pages in the inputs that were never successfully rendered (render pending or failed)

samples_in_index InventorySample

Sample in index URLs (only with include_samples)

Items: InventorySample

Default: null

samples_in_stale InventorySample

Sample stale URLs (only with include_samples)

Items: InventorySample

Default: null

samples_expired InventorySample

Sample expired URLs (only with include_samples)

Items: InventorySample

Default: null

samples_not_indexed InventorySample

Sample not indexed URLs (only with include_samples)

Items: InventorySample

Default: null

Endpoints

POST http://agents.botify.com/{organization}/{project}/speedworkers_inventory/process

POST http://agents.botify.com/{organization}/{project}/speedworkers_inventory/batch_process

POST http://agents.botify.com/{organization}/{project}/speedworkers_inventory/async_process

POST http://agents.botify.com/{organization}/{project}/speedworkers_inventory/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}/speedworkers_inventory/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {}
}'

Over MCP

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

Raw metadata

GET /agents/speedworkers_inventory — this page as JSON.
/agents/speedworkers_inventory/skill.md — Markdown for coding agents.