Trackers

A tracker re-runs a list or a search on a schedule and fires a webhook when a condition is met. It exists so nothing in your stack has to poll.

Tracking a list

curl -X POST https://api.unif.dev/v1/trackers \
  -H "Authorization: Bearer $UNIF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Competitor revenue swings",
    "source": { "type": "list", "list_id": "lst_01k3m9x7v2q8r4t6y0b1n5d7fa" },
    "schedule": "daily",
    "conditions": [
      { "metric": "revenue", "change": "pct", "over": "1d", "gte": 0.3 },
      { "metric": "revenue", "change": "pct", "over": "1d", "lte": -0.3 }
    ],
    "webhook_id": "whk_01k3m9x7v2q8r4t6y0b1n5d7fa"
  }'

Every member of the list is re-checked each cycle. Any member matching any condition fires the tracker.

Tracking a search

The other source type re-runs a query, which is how you catch entities you do not know about yet.

{
  "name": "New US beauty shops above $100k",
  "source": {
    "type": "search",
    "entity_type": "shop",
    "search": {
      "market": "US",
      "period": { "preset": "last_7d" },
      "filters": {
        "category_ids": ["cat_beauty_personal_care"],
        "revenue": { "gte": 100000 }
      }
    }
  },
  "schedule": "daily"
}

With no conditions, a search tracker fires on membership change — entities that entered or left the result set since the last run. That is the difference from a list tracker, which watches metrics on a fixed set.

Search trackers are how you find competitors before they are competitors. A shop crossing $100k in a category you own is worth knowing about the week it happens, not the quarter.

Conditions

{ "metric": "revenue", "change": "pct", "over": "7d", "gte": 0.3 }

string

required

Any metric defined on the tracked entity. See the metrics reference.

string

pct compares the ratio change against the previous window, abs the absolute change. Omit it entirely to test the current level instead — { "metric": "revenue", "lte": 1000 } fires while revenue sits below 1,000.

string

The comparison window: 1d, 7d or 30d. Defaults to 1d.

number

The bound. Set both to fire inside a band; use two separate conditions to fire outside one.

Multiple conditions are OR — any match fires. The pair in the first example catches both a 30% rise and a 30% fall, which is usually what “tell me when this moves” means.

A percentage change against a small base is noise. Pair a change condition with a level condition, or filter the underlying list to entities above a revenue floor, or you will get paged about a shop that went from

40 to

90.

Schedules

Schedule	Runs	Use for
`hourly`	Every hour	Live campaign monitoring, launch days
`daily`	Once per day after the daily refresh	Almost everything
`weekly`	Once per week	Category and market-level trends

Running more often than the data refreshes does not make it fresher. Most entities refresh daily — check typical_lag_hours in coverage before reaching for hourly.

What a firing delivers

The tracker posts a tracker.triggered event to its webhook, carrying the entities that matched and why.

{
  "id": "evt_01k3m9x7v2q8r4t6y0b1n5d7fa",
  "type": "tracker.triggered",
  "created_at": "2026-09-15T06:00:12Z",
  "data": {
    "tracker_id": "trk_01k3m9x7v2q8r4t6y0b1n5d7fa",
    "tracker_name": "Competitor revenue swings",
    "matches": [
      {
        "entity_id": "shp_01k3m9x7v2q8r4t6y0b1n5d7fa",
        "entity_type": "shop",
        "name": "GlowLab",
        "condition": { "metric": "revenue", "change": "pct", "over": "1d", "gte": 0.3 },
        "previous_value": 41200.0,
        "current_value": 58900.5,
        "change": 0.4296
      }
    ]
  }
}

A cycle with no matches delivers nothing. Silence means nothing crossed a threshold — not that the tracker failed. Read last_run_at on the tracker if you need to confirm it ran.

Operating them

One tracker per question

A tracker with six unrelated conditions produces events nobody can route. One tracker per thing you would actually act on keeps the webhook payload meaningful.

Set a floor

Filter the source list or search to entities big enough to matter before adding a percentage condition.

Check last_run_at

GET /trackers/{id} reports last_run_at and next_run_at. A tracker that has not run is a different problem from one that found nothing.

Delete what you stopped reading

Trackers consume credits on every cycle whether or not anyone acts on the output.

Getting started

Core concepts

Workflows

Guides

Platform

Release notes

Tracking a list

Tracking a search

Conditions

Schedules

What a firing delivers

Operating them

​Tracking a list

​Tracking a search

​Conditions

​Schedules

​What a firing delivers

​Operating them

Tracking a list

Tracking a search

Conditions

Schedules

What a firing delivers

Operating them