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

# Create a tracker

> Re-runs a saved search or re-checks a list on a schedule and emits a
`tracker.triggered` webhook when a condition is met. Trackers are how you stop polling.




## OpenAPI

````yaml /api-reference/openapi.yaml post /trackers
openapi: 3.1.0
info:
  title: Unif API
  version: '2026-09-01'
  summary: One schema for commerce data across every channel.
  description: >
    The Unif API returns normalized commerce data — shops, products, creators,
    videos,

    livestreams and categories — through a single schema that does not change
    when the

    underlying data source does.


    Each request runs a cascade across the sources behind a channel, in cost
    order, stopping at

    the first result that verifies. You are charged for the hit, not for the
    attempts. See

    [the waterfall](/docs/concepts/waterfall).


    Every response is denominated in the currency you ask for, scoped to a
    market, and

    measured over a period you control, whichever source answered.


    **Base URL**


    ```

    https://api.unif.dev/v1

    ```


    All requests require a bearer token. See
    [Authentication](/docs/authentication).


    **Conventions**


    - Success and failure are carried by the HTTP status code. There is no
    envelope to unwrap:
      a `200` body is the object itself, and any `4xx` or `5xx` body is an
      [error object](/docs/platform/errors).
    - Lists are cursor-paginated. Read `next_cursor` and stop when `has_more` is
    false.

    - Every response carries `X-Request-Id`. Billable responses also carry
      `X-Unif-Credits-Charged` and `X-Unif-Credits-Remaining`.
    - Monetary fields are converted to the `currency` you request, and every
    object repeats
      the `currency` and `period` it was measured under.
  contact:
    name: Unif Support
    email: support@unif.dev
    url: https://unif.dev/docs
  license:
    name: Proprietary
    url: https://unif.dev/legal/terms
servers:
  - url: https://api.unif.dev/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Meta
    description: Workspace, channel availability and field coverage.
  - name: Shops
    description: Storefronts and sellers.
  - name: Products
    description: Listings, pricing and sales performance.
  - name: Creators
    description: Affiliates and influencers who sell.
  - name: Videos
    description: Short-form video attributed to sales.
  - name: Livestreams
    description: Live selling sessions.
  - name: Categories
    description: The normalized category tree and category-level market data.
  - name: Resolution
    description: Turn a URL, handle or external ID into a Unif entity.
  - name: Jobs
    description: Asynchronous work for large searches, enrichments and exports.
  - name: Lists
    description: Saved sets of entities.
  - name: Trackers
    description: Scheduled re-checks that emit webhook events on change.
  - name: Webhooks
    description: Endpoint registration and delivery settings.
  - name: Usage
    description: Credit balance and per-request consumption.
paths:
  /trackers:
    post:
      tags:
        - Trackers
      summary: Create a tracker
      description: >
        Re-runs a saved search or re-checks a list on a schedule and emits a

        `tracker.triggered` webhook when a condition is met. Trackers are how
        you stop polling.
      operationId: createTracker
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackerCreateRequest'
            examples:
              competitorRevenueDrop:
                summary: Alert when a competitor's revenue moves sharply
                value:
                  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
      responses:
        '201':
          description: The created tracker.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tracker'
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    TrackerCreateRequest:
      type: object
      required:
        - name
        - source
        - schedule
      properties:
        name:
          type: string
        source:
          type: object
          description: What to re-check — a saved list, or a saved search re-run each time.
          properties:
            type:
              type: string
              enum:
                - list
                - search
            list_id:
              type: string
            entity_type:
              $ref: '#/components/schemas/EntityType'
            search:
              type: object
              additionalProperties: true
              description: A search request body, used when `type` is `search`.
        schedule:
          type: string
          enum:
            - hourly
            - daily
            - weekly
        conditions:
          type: array
          description: Any condition matching fires the tracker. Omit to fire on every run.
          items:
            $ref: '#/components/schemas/TrackerCondition'
        webhook_id:
          type: string
    Tracker:
      type: object
      properties:
        id:
          type: string
          examples:
            - trk_01k3m9x7v2q8r4t6y0b1n5d7fa
        object:
          type: string
          const: tracker
        name:
          type: string
        schedule:
          type: string
          enum:
            - hourly
            - daily
            - weekly
        enabled:
          type: boolean
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/TrackerCondition'
        webhook_id:
          type:
            - string
            - 'null'
        last_run_at:
          type:
            - string
            - 'null'
          format: date-time
        next_run_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
    EntityType:
      type: string
      enum:
        - shop
        - product
        - creator
        - video
        - livestream
        - category
    TrackerCondition:
      type: object
      description: >
        Fires when a metric crosses a bound. `change` compares against the
        previous window;

        omit it to test the absolute value.
      required:
        - metric
      properties:
        metric:
          type: string
          examples:
            - revenue
        change:
          type: string
          enum:
            - pct
            - abs
          description: Compare the change instead of the level.
        over:
          type: string
          enum:
            - 1d
            - 7d
            - 30d
          default: 1d
        gte:
          type: number
        lte:
          type: number
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
    Error:
      type: object
      properties:
        type:
          type: string
          enum:
            - invalid_request_error
            - authentication_error
            - permission_error
            - not_found_error
            - rate_limit_error
            - billing_error
            - coverage_error
            - api_error
        code:
          type: string
          examples:
            - parameter_invalid
        message:
          type: string
        param:
          type:
            - string
            - 'null'
          description: The offending field
          as a dot-path.: null
        doc_url:
          type: string
          format: uri
        request_id:
          type: string
  responses:
    BadRequest:
      description: The request was malformed or a parameter was invalid.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: invalid_request_error
              code: parameter_invalid
              message: filters.revenue.gte must be a non-negative number.
              param: filters.revenue.gte
              doc_url: https://unif.dev/docs/platform/errors#parameter_invalid
              request_id: req_01k3m9x7v2q8r4t6y0b1n5d7fa
  headers:
    RequestId:
      description: Unique ID for this request. Include it in support conversations.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Send your workspace API key as a bearer token:


        ```

        Authorization: Bearer unif_sk_live_...

        ```


        Keys are scoped to a single workspace. See
        [Authentication](/docs/authentication).

````