> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tako.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitors

export const MonitorsExperimental = () => <Warning>
    <strong>Monitors is experimental.</strong> Request and payload shapes can change without a deprecation window. Monitors isn't recommended for production workflows.
  </Warning>;

export const CodingAgentCTA = ({description, href}) => <p className="mt-2 text-lg prose prose-gray dark:prose-invert [&>*]:[overflow-wrap:anywhere]">
    {description} Building with a coding agent?{" "}
    <a href={href}>Give your agent the full reference →</a>
  </p>;

<CodingAgentCTA description="Watch Tako data for a condition, and get a signed webhook or a Slack message when it happens. Monitor stock moves, crypto and currency levels, and live sports, without polling." href="/documentation/integrating-tako/monitors/for-coding-agent" />

<MonitorsExperimental />

## How monitors work

A monitor is a condition on Tako data, such as "AAPL moves up 3% in a day" or "the 49ers win." Tako evaluates the condition when new data arrives. When the condition occurs, Tako posts a signed request to your endpoint. You don't poll, and you don't schedule anything.

You work with four objects:

| Object                   | What it is                                                                                                                                                                                                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Monitor type**         | A kind of condition, such as `stocks.pct_change`. Each type publishes the parameters it takes and says when it fires.                                                                                                                                                           |
| **Monitor**              | One condition that you create from a type, with your parameters: a subject, such as a ticker or a game, and a threshold.                                                                                                                                                        |
| **Notification channel** | Where Tako posts firings: an `https` endpoint that you own, or a Slack workflow that posts to a Slack channel. Tako signs every request it sends to a channel with the channel's secret. See [Webhook deliveries](/documentation/integrating-tako/monitors/webhook-deliveries). |
| **Firing**               | One occurrence of a monitor's condition. Tako records the firing and sends one delivery to each channel on the monitor.                                                                                                                                                         |

## Supported monitor types

Tako supports four domains of monitor types. For the current list and each type's parameters, call [List monitor types](/api-reference/monitor-types).

<CardGroup cols={2}>
  <Card title="Stocks" icon="chart-line">
    A stock moves by a percentage over a day, a week, or a month. A stock's price crosses a level you set. A stock sets a new 52-week high or low.
  </Card>

  <Card title="Crypto" icon="bitcoin-sign">
    A crypto asset's price in US dollars reaches a level you set. You name the asset by its ticker or its CoinMarketCap id.
  </Card>

  <Card title="Forex" icon="money-bill-transfer">
    A currency pair's rate reaches a level you set, such as EUR/USD above 1.15.
  </Card>

  <Card title="Sports" icon="football">
    A game starts, a game ends, a team scores, or a betting line reaches a level you set. You can watch one game, or follow one team across its games.
  </Card>
</CardGroup>

## What to know before you start

* **A monitor fires only for what happens after you create it.** You can't use a monitor to search history.
* **Most monitors fire once.** By default, Tako pauses a monitor after its first firing. To fire on every new occurrence, set `fire_once` to `false`. The crypto and forex level types always fire once.
* **A firing reports when the condition occurred, not the current value.** Each source reports new data on its own schedule. Each type's description in [List monitor types](/api-reference/monitor-types) says how far its source runs behind.
* **By default, you can hold 1 active monitor and 2 notification channels.** Tako counts these limits per user. A `LIMIT_REACHED` response's `limit` gives your cap. To free a monitor slot, pause or delete a monitor. For higher limits, contact [support@tako.com](mailto:support@tako.com).
* **The monitors endpoints allow 120 calls per minute, and 20,000 per day.** Each call takes the `X-API-Key` header that every Tako endpoint uses.

## Examples

To build `parameters` for another type, read its `parameters_schema` in [List monitor types](/api-reference/monitor-types).

### Monitor AAPL for a 3% daily rise

<Steps>
  <Step title="Create a notification channel">
    ```bash theme={null}
    CHANNEL=$(curl -s -X POST https://tako.com/api/v1/notification_channels \
      -H "X-API-Key: $TAKO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name": "My receiver", "kind": "webhook", "url": "https://api.example.com/tako/webhooks"}')
    CHANNEL_ID=$(echo "$CHANNEL" | jq -r .id)
    echo "$CHANNEL" | jq -r .secret > tako-webhook-secret.txt
    ```

    `CHANNEL_ID` holds the channel's `id`, and `tako-webhook-secret.txt` holds its signing `secret`. Store the secret now, because no later request returns it.
  </Step>

  <Step title="Create the monitor">
    ```bash theme={null}
    AAPL_MONITOR=$(curl -s -X POST https://tako.com/api/v1/monitors \
      -H "X-API-Key: $TAKO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "AAPL up 3% in a day",
        "type": "stocks.pct_change",
        "parameters": {"ticker": "AAPL", "window": "1d", "threshold": 3, "direction": "up"},
        "fire_once": false,
        "channel_ids": ["'"$CHANNEL_ID"'"]
      }')
    AAPL_MONITOR_ID=$(echo "$AAPL_MONITOR" | jq -r .id)
    echo "$AAPL_MONITOR" | jq .subject
    ```

    `fire_once: false` keeps the monitor active after it fires, so it fires again on the next day that AAPL rises 3%. `subject` in the response names the listing that Tako matched: `AAPL` on `XNAS`, Apple Inc.
  </Step>

  <Step title="Receive the firing">
    On a day that AAPL rises 3% or more from the prior session's close, Tako posts a `monitor.fired` event to your channel. This excerpt shows the body's `summary` and `payload`:

    ```json theme={null}
    {
      "type": "monitor.fired",
      "summary": "AAPL is at 233.70, up 3.2% from its 226.41 close on 2026-09-11, past your 3% threshold.",
      "payload": {
        "ticker": "AAPL",
        "exchange": "XNAS",
        "window": "1d",
        "baseline_date": "2026-09-11",
        "baseline_close": 226.41,
        "price": 233.7,
        "percent_change": 3.2188
      }
    }
    ```

    Verify the signature before you trust the body. For the full body and the verification code, see [Webhook deliveries](/documentation/integrating-tako/monitors/webhook-deliveries).
  </Step>
</Steps>

### Monitor every 49ers win

This example posts to the channel you created in the preceding example. By default, you can hold 1 active monitor, so this example pauses the AAPL monitor before it creates a new one.

<Steps>
  <Step title="Find the 49ers' team id">
    ```bash theme={null}
    TEAM_ID=$(curl -s "https://tako.com/api/v1/sports/games?league=NFL" \
      -H "X-API-Key: $TAKO_API_KEY" \
      | jq -r '.items[] | .home, .away | select(.name != null and (.name | test("49ers"))) | .id' | head -1)
    echo "$TEAM_ID"
    ```

    Each game in the response names its `home` and `away` teams, with an `id` for each. The list covers one day back to seven days ahead. The NFL plays every week from September to February, so the 49ers appear in most weeks of the season. If `TEAM_ID` is empty, the 49ers have no game in that window. A team's id doesn't change, so you can store it and reuse it when the team has no game in the window.
  </Step>

  <Step title="Pause the AAPL monitor">
    ```bash theme={null}
    curl -X PATCH https://tako.com/api/v1/monitors/$AAPL_MONITOR_ID \
      -H "X-API-Key: $TAKO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"status": "paused"}'
    ```

    A paused monitor doesn't count toward your limit.
  </Step>

  <Step title="Create the monitor">
    ```bash theme={null}
    curl -X POST https://tako.com/api/v1/monitors \
      -H "X-API-Key: $TAKO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "49ers wins",
        "type": "sports.game_result",
        "parameters": {"team_id": "'"$TEAM_ID"'", "outcome": "wins"},
        "fire_once": false,
        "channel_ids": ["'"$CHANNEL_ID"'"]
      }'
    ```

    A `team_id` without a `game_id` follows the team from game to game. `fire_once: false` keeps the monitor active for the whole season.
  </Step>

  <Step title="Receive the firing">
    When a 49ers game ends in a win, Tako posts a `monitor.fired` event to your channel. This excerpt shows the body's `summary` and part of its `payload`:

    ```json theme={null}
    {
      "type": "monitor.fired",
      "summary": "San Francisco 49ers beat Los Angeles Rams 27 to 20.",
      "payload": {
        "team": "San Francisco 49ers",
        "opponent": "Los Angeles Rams",
        "home_team": "San Francisco 49ers",
        "away_team": "Los Angeles Rams",
        "team_score": 27,
        "opponent_score": 20,
        "outcome": "wins",
        "margin": 7,
        "winner": "San Francisco 49ers"
      }
    }
    ```

    To fire only on a win by 10 points or more, add `"margin": 10` to `parameters`.
  </Step>
</Steps>

To post each 49ers win to a Slack channel, register a `slack_workflow` notification channel, and attach it to the monitor. See [Send monitor firings to Slack](/documentation/integrating-tako/monitors/slack).

## Next steps

* **[For your coding agent](/documentation/integrating-tako/monitors/for-coding-agent)**: the complete build reference, covering subjects, deliveries, debugging, and common mistakes.
* **[Webhook deliveries](/documentation/integrating-tako/monitors/webhook-deliveries)**: the request body, signature verification, and how Tako retries a delivery.
* **[Send monitor firings to Slack](/documentation/integrating-tako/monitors/slack)**: a Slack workflow that posts each firing to a Slack channel.
* **[List monitor types](/api-reference/monitor-types)**: every type and the parameters it takes.