Agency

Agency API reference

Every endpoint of the agency API, with its fields, an example response, and curl and Node examples.

Authenticate with an account API key in X-API-Key; GET needs agency:read and everything else agency:write. Send an Idempotency-Key on every POST. How authentication, errors, pagination and rate limits work is on the Agency API page.

Endpoints

41 endpoints in 6 groups. Paths are relative to https://api.seentics.com.

Overview

GETTotals, per-client trends, top movers and alerts
POSTDismiss an alert
GETSetup guide progress

Clients

GETList clients
POSTCreate a client
GETGet a client with its websites
PATCHUpdate a client
POSTArchive a client
POSTRestore an archived client
DELETEDelete a client
GETList a client’s websites
POSTAdd a website to a client
GETDashboard pages the client can see
PUTSet which dashboard pages the client can see
GETList a client’s users
POSTInvite a client user
PATCHRename, disable or enable a client user
DELETERemove a client user
POSTEmail a new sign-in link

Websites

GETList websites
POSTCreate a website
GETGet a website
PATCHRename or move a website
DELETEDelete a website and everything it collected
GETInstall snippet, instructions and tracking status
POSTCheck again whether events are arriving

Branding

GETWhite-label settings
PUTSave white-label settings
GETCustom domain and its state
PUTAdd or replace the custom domain
POSTCheck DNS and the certificate now
DELETERemove the custom domain

Embeds

GETList embed links
POSTCreate an embed link
PATCHChange what an embed link shows
DELETERevoke an embed link

Usage

GETThis month’s pool, use, allocation and overage
GETUse per client this month
GETUse per website this month
GETOne client’s use this month, with its websites
GETOne website’s use this month

Overview

GET/api/v1/agency/overview

Totals, per-client trends, top movers and alertsScope agency:read

Query

Name	Type	Description
`period`	string	`7d`, `30d` or `90d`; default `30d`.

Response 200

{
  "data": {
    "period": {
      "key": "30d",
      "start": "2026-09-17",
      "end": "2026-10-16",
      "previous_start": "2026-08-18",
      "previous_end": "2026-09-16"
    },
    "totals": {
      "visitors": 48210,
      "pageviews": 131004,
      "events": 412000,
      "recordings": 2100,
      "leads": 88
    },
    "previous_totals": {
      "visitors": 42890,
      "pageviews": 120310,
      "events": 380200,
      "recordings": 1950,
      "leads": 71
    },
    "clients": [
      {
        "id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
        "name": "Acme Bakery",
        "status": "active",
        "website_count": 1,
        "totals": {
          "visitors": 48210,
          "events": 412000,
          "leads": 88
        },
        "previous_totals": {
          "visitors": 42890,
          "events": 380200,
          "leads": 71
        }
      }
    ],
    "top_movers": [
      {
        "website_id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
        "website_name": "Acme Bakery",
        "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
        "metric": "visitors",
        "current": 48210,
        "previous": 42890,
        "change_pct": 12.4
      }
    ],
    "alerts": [
      {
        "id": "c0b5d1e2-7a44-4f0e-9b1a-3d2e6f8a9b10",
        "kind": "tracking_stopped",
        "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
        "website_id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
        "resource": "events",
        "period": "2026-10-16",
        "created_at": "2026-10-16T06:00:00.000Z",
        "dismissed_at": null
      }
    ],
    "generated_at": "2026-10-17T09:00:00.000Z"
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/overview?period=30d" \
  -H "X-API-Key: $SEENTICS_API_KEY"

POST/api/v1/agency/alerts/:id/dismiss

Dismiss an alertScope agency:write · send an Idempotency-Key

Path parameters

Name	Type	Description
`id`required	uuid	The alert’s ID.

Response 200

{
  "data": {
    "id": "c0b5d1e2-7a44-4f0e-9b1a-3d2e6f8a9b10",
    "kind": "tracking_stopped",
    "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
    "website_id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
    "resource": "events",
    "period": "2026-10-16",
    "created_at": "2026-10-16T06:00:00.000Z",
    "dismissed_at": "2026-10-17T09:00:00.000Z"
  }
}

curl

curl -X POST "https://api.seentics.com/api/v1/agency/alerts/c0b5d1e2-7a44-4f0e-9b1a-3d2e6f8a9b10/dismiss" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

GET/api/v1/agency/setup

Setup guide progressScope agency:read

Response 200

{
  "data": {
    "steps": [
      {
        "id": "branding",
        "done": true
      },
      {
        "id": "first_client",
        "done": true
      },
      {
        "id": "website_installed",
        "done": false
      },
      {
        "id": "client_user",
        "done": false
      },
      {
        "id": "features_limits",
        "done": false
      }
    ]
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/setup" \
  -H "X-API-Key: $SEENTICS_API_KEY"

Clients

GET/api/v1/agency/clients

List clientsScope agency:read

Query

Name	Type	Description
`status`	"active" \| "suspended" \| "archived"	Only clients in this status.
`q`	string	Search name and company.
`limit`	integer	Up to 100 rows; default 25.
`cursor`	string	The `next_cursor` of the previous page.

Response 200

{
  "data": [
    {
      "id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
      "name": "Acme Bakery",
      "company": "Acme Bakery Ltd",
      "notes": "",
      "status": "active",
      "website_count": 1,
      "collect_features": {
        "analytics": true,
        "heatmaps": true,
        "replays": true,
        "funnels": true,
        "automations": true,
        "errors": true
      },
      "created_at": "2026-10-09T07:50:21.158Z",
      "updated_at": "2026-10-09T07:50:21.158Z"
    }
  ],
  "page": {
    "next_cursor": null,
    "has_more": false
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/clients?status=active" \
  -H "X-API-Key: $SEENTICS_API_KEY"

POST/api/v1/agency/clients

Create a clientScope agency:write · send an Idempotency-Key

Body

Name	Type	Description
`name`required	string	Client name, 1–120 characters.
`company`	string	Company name, up to 200 characters.
`notes`	string	Private notes, up to 2000 characters.

Request body

{
  "name": "Acme Bakery",
  "company": "Acme Bakery Ltd"
}

Response 201

{
  "data": {
    "id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
    "name": "Acme Bakery",
    "company": "Acme Bakery Ltd",
    "notes": "",
    "status": "active",
    "website_count": 0,
    "collect_features": {
      "analytics": true,
      "heatmaps": true,
      "replays": true,
      "funnels": true,
      "automations": true,
      "errors": true
    },
    "created_at": "2026-10-09T07:50:21.158Z",
    "updated_at": "2026-10-09T07:50:21.158Z",
    "websites": []
  }
}

curl

curl -X POST "https://api.seentics.com/api/v1/agency/clients" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Bakery","company":"Acme Bakery Ltd"}'

GET/api/v1/agency/clients/:id

Get a client with its websitesScope agency:read

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.

Response 200

{
  "data": {
    "id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
    "name": "Acme Bakery",
    "company": "Acme Bakery Ltd",
    "notes": "",
    "status": "active",
    "website_count": 1,
    "collect_features": {
      "analytics": true,
      "heatmaps": true,
      "replays": true,
      "funnels": true,
      "automations": true,
      "errors": true
    },
    "created_at": "2026-10-09T07:50:21.158Z",
    "updated_at": "2026-10-09T07:50:21.158Z",
    "websites": [
      {
        "id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
        "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
        "name": "Acme Bakery",
        "url": "https://acmebakery.test",
        "tracking_id": "ST-76d3842a9594c586",
        "is_active": true,
        "is_verified": true,
        "created_at": "2026-10-09T07:52:33.324Z",
        "updated_at": "2026-10-09T07:52:33.324Z"
      }
    ]
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94" \
  -H "X-API-Key: $SEENTICS_API_KEY"

PATCH/api/v1/agency/clients/:id

Update a clientAbsent fields keep their value.Scope agency:write

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.

Body

Name	Type	Description
`name`	string	Client name, 1–120 characters.
`company`	string	Company name, up to 200 characters.
`notes`	string	Private notes, up to 2000 characters.
`status`	"active" \| "suspended" \| "archived"	Anything but `active` stops its websites collecting.
`collect_features`	Record<"analytics" \| "heatmaps" \| "replays" \| "funnels" \| "automations" \| "errors", boolean>	What its websites collect; `analytics: false` stops collection entirely.

Request body

{
  "notes": "Renews in March"
}

Response 200

{
  "data": {
    "id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
    "name": "Acme Bakery",
    "company": "Acme Bakery Ltd",
    "notes": "Renews in March",
    "status": "active",
    "website_count": 1,
    "collect_features": {
      "analytics": true,
      "heatmaps": true,
      "replays": true,
      "funnels": true,
      "automations": true,
      "errors": true
    },
    "created_at": "2026-10-09T07:50:21.158Z",
    "updated_at": "2026-10-09T07:50:21.158Z",
    "websites": [
      {
        "id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
        "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
        "name": "Acme Bakery",
        "url": "https://acmebakery.test",
        "tracking_id": "ST-76d3842a9594c586",
        "is_active": true,
        "is_verified": true,
        "created_at": "2026-10-09T07:52:33.324Z",
        "updated_at": "2026-10-09T07:52:33.324Z"
      }
    ]
  }
}

curl

curl -X PATCH "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notes":"Renews in March"}'

POST/api/v1/agency/clients/:id/archive

Archive a clientIts websites stop collecting until it is restored.Scope agency:write · send an Idempotency-Key

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.

Response 200

{
  "data": {
    "id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
    "name": "Acme Bakery",
    "company": "Acme Bakery Ltd",
    "notes": "",
    "status": "archived",
    "website_count": 1,
    "collect_features": {
      "analytics": true,
      "heatmaps": true,
      "replays": true,
      "funnels": true,
      "automations": true,
      "errors": true
    },
    "created_at": "2026-10-09T07:50:21.158Z",
    "updated_at": "2026-10-09T07:50:21.158Z",
    "websites": [
      {
        "id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
        "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
        "name": "Acme Bakery",
        "url": "https://acmebakery.test",
        "tracking_id": "ST-76d3842a9594c586",
        "is_active": true,
        "is_verified": true,
        "created_at": "2026-10-09T07:52:33.324Z",
        "updated_at": "2026-10-09T07:52:33.324Z"
      }
    ]
  }
}

curl

curl -X POST "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94/archive" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

POST/api/v1/agency/clients/:id/unarchive

Restore an archived clientScope agency:write · send an Idempotency-Key

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.

Response 200

{
  "data": {
    "id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
    "name": "Acme Bakery",
    "company": "Acme Bakery Ltd",
    "notes": "",
    "status": "active",
    "website_count": 1,
    "collect_features": {
      "analytics": true,
      "heatmaps": true,
      "replays": true,
      "funnels": true,
      "automations": true,
      "errors": true
    },
    "created_at": "2026-10-09T07:50:21.158Z",
    "updated_at": "2026-10-09T07:50:21.158Z",
    "websites": [
      {
        "id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
        "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
        "name": "Acme Bakery",
        "url": "https://acmebakery.test",
        "tracking_id": "ST-76d3842a9594c586",
        "is_active": true,
        "is_verified": true,
        "created_at": "2026-10-09T07:52:33.324Z",
        "updated_at": "2026-10-09T07:52:33.324Z"
      }
    ]
  }
}

curl

curl -X POST "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94/unarchive" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

DELETE/api/v1/agency/clients/:id

Delete a clientRequires confirm=true. Its websites stay in your account, no longer assigned.Scope agency:write

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.

Query

Name	Type	Description
`confirm`required	boolean	Must be `true`.

Answers 204 with no body.

curl

curl -X DELETE "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94?confirm=true" \
  -H "X-API-Key: $SEENTICS_API_KEY"

GET/api/v1/agency/clients/:id/websites

List a client’s websitesScope agency:read

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.

Query

Name	Type	Description
`limit`	integer	Up to 100 rows; default 25.
`cursor`	string	The `next_cursor` of the previous page.

Response 200

{
  "data": [
    {
      "id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
      "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
      "name": "Acme Bakery",
      "url": "https://acmebakery.test",
      "tracking_id": "ST-76d3842a9594c586",
      "is_active": true,
      "is_verified": true,
      "created_at": "2026-10-09T07:52:33.324Z",
      "updated_at": "2026-10-09T07:52:33.324Z"
    }
  ],
  "page": {
    "next_cursor": null,
    "has_more": false
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94/websites" \
  -H "X-API-Key: $SEENTICS_API_KEY"

POST/api/v1/agency/clients/:id/websites

Add a website to a clientAnswers with the website and its install snippet.Scope agency:write · send an Idempotency-Key

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.

Body

Name	Type	Description
`name`required	string	Website name.
`url`required	string	The site’s address.

Request body

{
  "name": "Acme Bakery",
  "url": "https://acmebakery.test"
}

Response 201

{
  "data": {
    "website": {
      "id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
      "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
      "name": "Acme Bakery",
      "url": "https://acmebakery.test",
      "tracking_id": "ST-76d3842a9594c586",
      "is_active": true,
      "is_verified": false,
      "created_at": "2026-10-09T07:52:33.324Z",
      "updated_at": "2026-10-09T07:52:33.324Z"
    },
    "install": {
      "website_id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
      "tracking_id": "ST-76d3842a9594c586",
      "script_url": "https://seentics.com/trackers/seentics.min.js",
      "snippet_html": "<script defer data-website-id=\"2f60eb30-722c-4fbf-8afa-99fe0e67f6d9\" src=\"https://seentics.com/trackers/seentics.min.js\"></script>",
      "instructions": {
        "html": {
          "summary": "Paste this tag into the <head> of every page: <script defer data-website-id=\"2f60eb30-722c-4fbf-8afa-99fe0e67f6d9\" src=\"https://seentics.com/trackers/seentics.min.js\"></script>",
          "docs_url": "https://seentics.com/docs/tracker"
        },
        "gtm": {
          "summary": "In Google Tag Manager, add a Custom HTML tag with the snippet, fired on All Pages, then publish the container.",
          "docs_url": "https://seentics.com/docs/google-tag-manager"
        },
        "nextjs": {
          "summary": "npm i @seentics/next, then render <Seentics websiteId=\"2f60eb30-722c-4fbf-8afa-99fe0e67f6d9\" /> in the root layout.",
          "docs_url": "https://seentics.com/docs/frameworks#nextjs"
        },
        "wordpress": {
          "summary": "Install the Seentics plugin and paste the website ID 2f60eb30-722c-4fbf-8afa-99fe0e67f6d9 into its settings.",
          "docs_url": "https://seentics.com/docs/wordpress"
        },
        "shopify": {
          "summary": "Paste the snippet into theme.liquid before </head>, and add the Seentics custom pixel for purchases.",
          "docs_url": "https://seentics.com/docs/shopify"
        },
        "npm": {
          "summary": "npm i @seentics/react (or vue, nuxt, astro, svelte) and pass websiteId \"2f60eb30-722c-4fbf-8afa-99fe0e67f6d9\" to its component.",
          "docs_url": "https://seentics.com/docs/frameworks"
        }
      },
      "verification": {
        "status": "not_seen",
        "is_verified": false,
        "last_event_at": null,
        "events_24h": 0
      }
    }
  }
}

curl

curl -X POST "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94/websites" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Bakery","url":"https://acmebakery.test"}'

GET/api/v1/agency/clients/:id/features

Dashboard pages the client can seeScope agency:read

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.

Response 200

{
  "data": {
    "features": {
      "overview": "view",
      "events": "view",
      "paths": "view",
      "revenue": "off",
      "recordings": "off",
      "heatmaps": "view",
      "funnels": "view",
      "goals": "edit",
      "automations": "off",
      "leads": "off",
      "conversions": "off",
      "ai": "off",
      "errors": "off",
      "privacy": "view"
    }
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94/features" \
  -H "X-API-Key: $SEENTICS_API_KEY"

PUT/api/v1/agency/clients/:id/features

Set which dashboard pages the client can seeEach feature is off, view or edit; a feature left out is off. Client users see only pages set to view or edit, and change things only on edit; any other request answers 403 feature_not_allowed.Scope agency:write

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.

Body

Name	Type	Description
`features`required	Record<feature, "off" \| "view" \| "edit">	Every feature id.

Request body

{
  "features": {
    "overview": "view",
    "events": "view",
    "paths": "view",
    "revenue": "off",
    "recordings": "off",
    "heatmaps": "view",
    "funnels": "view",
    "goals": "edit",
    "automations": "off",
    "leads": "off",
    "conversions": "off",
    "ai": "off",
    "errors": "off",
    "privacy": "view"
  }
}

Response 200

{
  "data": {
    "features": {
      "overview": "view",
      "events": "view",
      "paths": "view",
      "revenue": "off",
      "recordings": "off",
      "heatmaps": "view",
      "funnels": "view",
      "goals": "edit",
      "automations": "off",
      "leads": "off",
      "conversions": "off",
      "ai": "off",
      "errors": "off",
      "privacy": "view"
    }
  }
}

curl

curl -X PUT "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94/features" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"features":{"overview":"view","events":"view","paths":"view","revenue":"off","recordings":"off","heatmaps":"view","funnels":"view","goals":"edit","automations":"off","leads":"off","conversions":"off","ai":"off","errors":"off","privacy":"view"}}'

GET/api/v1/agency/clients/:id/users

List a client’s usersThe people who sign in to the client’s dashboard with an email link.Scope agency:read

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.

Query

Name	Type	Description
`limit`	integer	Up to 100 rows; default 25.
`cursor`	string	The `next_cursor` of the previous page.

Response 200

{
  "data": [
    {
      "id": "6d2c8e14-3b5a-4f7e-a1c9-0e8b7d6f5a42",
      "email": "jess@acmebakery.test",
      "name": "Jess Baker",
      "status": "active",
      "invited_at": "2026-10-12T10:00:00.000Z",
      "last_seen_at": "2026-10-16T08:12:44.000Z"
    }
  ],
  "page": {
    "next_cursor": null,
    "has_more": false
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94/users" \
  -H "X-API-Key: $SEENTICS_API_KEY"

POST/api/v1/agency/clients/:id/users

Invite a client userAdds the person and emails them a sign-in link, branded with your branding.Scope agency:write · send an Idempotency-Key

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.

Body

Name	Type	Description
`email`required	string	Where the sign-in link goes.
`name`	string	Their name, up to 120 characters.

Request body

{
  "email": "jess@acmebakery.test",
  "name": "Jess Baker"
}

Response 201

{
  "data": {
    "id": "6d2c8e14-3b5a-4f7e-a1c9-0e8b7d6f5a42",
    "email": "jess@acmebakery.test",
    "name": "Jess Baker",
    "status": "invited",
    "invited_at": "2026-10-12T10:00:00.000Z",
    "last_seen_at": null
  }
}

curl

curl -X POST "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94/users" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"email":"jess@acmebakery.test","name":"Jess Baker"}'

PATCH/api/v1/agency/clients/:id/users/:userId

Rename, disable or enable a client userDisabling signs the person out at once.Scope agency:write

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.
`userId`required	uuid	The client user’s ID.

Body

Name	Type	Description
`status`	"active" \| "disabled"	`disabled` stops their sign-in.
`name`	string	Their name.

Request body

{
  "status": "disabled"
}

Response 200

{
  "data": {
    "id": "6d2c8e14-3b5a-4f7e-a1c9-0e8b7d6f5a42",
    "email": "jess@acmebakery.test",
    "name": "Jess Baker",
    "status": "disabled",
    "invited_at": "2026-10-12T10:00:00.000Z",
    "last_seen_at": "2026-10-16T08:12:44.000Z"
  }
}

curl

curl -X PATCH "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94/users/6d2c8e14-3b5a-4f7e-a1c9-0e8b7d6f5a42" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

DELETE/api/v1/agency/clients/:id/users/:userId

Remove a client userThey lose access at once.Scope agency:write

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.
`userId`required	uuid	The client user’s ID.

Answers 204 with no body.

curl

curl -X DELETE "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94/users/6d2c8e14-3b5a-4f7e-a1c9-0e8b7d6f5a42" \
  -H "X-API-Key: $SEENTICS_API_KEY"

POST/api/v1/agency/clients/:id/users/:userId/send-link

Email a new sign-in linkThe link works once, for 15 minutes.Scope agency:write · send an Idempotency-Key

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.
`userId`required	uuid	The client user’s ID.

Response 202

{
  "data": {
    "sent": true
  }
}

curl

curl -X POST "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94/users/6d2c8e14-3b5a-4f7e-a1c9-0e8b7d6f5a42/send-link" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Websites

GET/api/v1/agency/websites

List websitesScope agency:read

Query

Name	Type	Description
`client_id`	uuid	Only this client’s websites.
`unassigned`	boolean	`true` for websites with no client.
`q`	string	Search name and URL.
`limit`	integer	Up to 100 rows; default 25.
`cursor`	string	The `next_cursor` of the previous page.

Response 200

{
  "data": [
    {
      "id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
      "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
      "name": "Acme Bakery",
      "url": "https://acmebakery.test",
      "tracking_id": "ST-76d3842a9594c586",
      "is_active": true,
      "is_verified": true,
      "created_at": "2026-10-09T07:52:33.324Z",
      "updated_at": "2026-10-09T07:52:33.324Z"
    }
  ],
  "page": {
    "next_cursor": null,
    "has_more": false
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/websites?unassigned=true" \
  -H "X-API-Key: $SEENTICS_API_KEY"

POST/api/v1/agency/websites

Create a websiteRead its snippet from GET /agency/websites/:id/install.Scope agency:write · send an Idempotency-Key

Body

Name	Type	Description
`name`required	string	Website name.
`url`required	string	The site’s address.
`client_id`	uuid \| null	The client to put it under.

Request body

{
  "name": "Acme Bakery",
  "url": "https://acmebakery.test",
  "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94"
}

Response 201

{
  "data": {
    "id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
    "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
    "name": "Acme Bakery",
    "url": "https://acmebakery.test",
    "tracking_id": "ST-76d3842a9594c586",
    "is_active": true,
    "is_verified": false,
    "created_at": "2026-10-09T07:52:33.324Z",
    "updated_at": "2026-10-09T07:52:33.324Z"
  }
}

curl

curl -X POST "https://api.seentics.com/api/v1/agency/websites" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Bakery","url":"https://acmebakery.test","client_id":"5bbeaa88-b089-4923-ad54-8fdcbbcdba94"}'

GET/api/v1/agency/websites/:id

Get a websiteScope agency:read

Path parameters

Name	Type	Description
`id`required	uuid	The website’s ID.

Response 200

{
  "data": {
    "id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
    "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
    "name": "Acme Bakery",
    "url": "https://acmebakery.test",
    "tracking_id": "ST-76d3842a9594c586",
    "is_active": true,
    "is_verified": true,
    "created_at": "2026-10-09T07:52:33.324Z",
    "updated_at": "2026-10-09T07:52:33.324Z"
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/websites/2f60eb30-722c-4fbf-8afa-99fe0e67f6d9" \
  -H "X-API-Key: $SEENTICS_API_KEY"

PATCH/api/v1/agency/websites/:id

Rename or move a websiteclient_id: null takes the website out of any client.Scope agency:write

Path parameters

Name	Type	Description
`id`required	uuid	The website’s ID.

Body

Name	Type	Description
`name`	string	Website name.
`url`	string	The site’s address.
`client_id`	uuid \| null	Move it to this client, or `null`.

Request body

{
  "client_id": null
}

Response 200

{
  "data": {
    "id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
    "client_id": null,
    "name": "Acme Bakery",
    "url": "https://acmebakery.test",
    "tracking_id": "ST-76d3842a9594c586",
    "is_active": true,
    "is_verified": true,
    "created_at": "2026-10-09T07:52:33.324Z",
    "updated_at": "2026-10-09T07:52:33.324Z"
  }
}

curl

curl -X PATCH "https://api.seentics.com/api/v1/agency/websites/2f60eb30-722c-4fbf-8afa-99fe0e67f6d9" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id":null}'

DELETE/api/v1/agency/websites/:id

Delete a website and everything it collectedScope agency:write

Path parameters

Name	Type	Description
`id`required	uuid	The website’s ID.

Answers 204 with no body.

curl

curl -X DELETE "https://api.seentics.com/api/v1/agency/websites/2f60eb30-722c-4fbf-8afa-99fe0e67f6d9" \
  -H "X-API-Key: $SEENTICS_API_KEY"

GET/api/v1/agency/websites/:id/install

Install snippet, instructions and tracking statusScope agency:read

Path parameters

Name	Type	Description
`id`required	uuid	The website’s ID.

Response 200

{
  "data": {
    "website_id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
    "tracking_id": "ST-76d3842a9594c586",
    "script_url": "https://seentics.com/trackers/seentics.min.js",
    "snippet_html": "<script defer data-website-id=\"2f60eb30-722c-4fbf-8afa-99fe0e67f6d9\" src=\"https://seentics.com/trackers/seentics.min.js\"></script>",
    "instructions": {
      "html": {
        "summary": "Paste this tag into the <head> of every page: <script defer data-website-id=\"2f60eb30-722c-4fbf-8afa-99fe0e67f6d9\" src=\"https://seentics.com/trackers/seentics.min.js\"></script>",
        "docs_url": "https://seentics.com/docs/tracker"
      },
      "gtm": {
        "summary": "In Google Tag Manager, add a Custom HTML tag with the snippet, fired on All Pages, then publish the container.",
        "docs_url": "https://seentics.com/docs/google-tag-manager"
      },
      "nextjs": {
        "summary": "npm i @seentics/next, then render <Seentics websiteId=\"2f60eb30-722c-4fbf-8afa-99fe0e67f6d9\" /> in the root layout.",
        "docs_url": "https://seentics.com/docs/frameworks#nextjs"
      },
      "wordpress": {
        "summary": "Install the Seentics plugin and paste the website ID 2f60eb30-722c-4fbf-8afa-99fe0e67f6d9 into its settings.",
        "docs_url": "https://seentics.com/docs/wordpress"
      },
      "shopify": {
        "summary": "Paste the snippet into theme.liquid before </head>, and add the Seentics custom pixel for purchases.",
        "docs_url": "https://seentics.com/docs/shopify"
      },
      "npm": {
        "summary": "npm i @seentics/react (or vue, nuxt, astro, svelte) and pass websiteId \"2f60eb30-722c-4fbf-8afa-99fe0e67f6d9\" to its component.",
        "docs_url": "https://seentics.com/docs/frameworks"
      }
    },
    "verification": {
      "status": "receiving",
      "is_verified": true,
      "last_event_at": "2026-10-16T22:41:07.000Z",
      "events_24h": 1824
    }
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/websites/2f60eb30-722c-4fbf-8afa-99fe0e67f6d9/install" \
  -H "X-API-Key: $SEENTICS_API_KEY"

POST/api/v1/agency/websites/:id/verify

Check again whether events are arrivingScope agency:write · send an Idempotency-Key

Path parameters

Name	Type	Description
`id`required	uuid	The website’s ID.

Response 200

{
  "data": {
    "status": "receiving",
    "is_verified": true,
    "last_event_at": "2026-10-16T22:41:07.000Z",
    "events_24h": 1824
  }
}

curl

curl -X POST "https://api.seentics.com/api/v1/agency/websites/2f60eb30-722c-4fbf-8afa-99fe0e67f6d9/verify" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Branding

GET/api/v1/agency/branding

White-label settingsScope agency:read

Response 200

{
  "data": {
    "brand_name": "Meridian Digital",
    "logo_url": "https://cdn.meridian.test/logo.png",
    "primary_color": "#7c3aed",
    "support_email": "help@meridian.test",
    "footer_text": "Reports by Meridian Digital",
    "hide_seentics": true,
    "slug": "meridian",
    "updated_at": "2026-10-12T10:00:00.000Z"
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/branding" \
  -H "X-API-Key: $SEENTICS_API_KEY"

PUT/api/v1/agency/branding

Save white-label settingsScope agency:write

Body

Name	Type	Description
`brand_name`	string	Shown in place of Seentics.
`logo_url`	string	An https:// image address.
`primary_color`	string	Hex colour, e.g. `#7c3aed`.
`support_email`	string	Where clients write for help.
`footer_text`	string	A line under every page.
`hide_seentics`	boolean	Drop “Powered by Seentics”.
`slug`	string \| null	3–40 characters a–z, 0–9 and hyphens; your sign-in name on seentics.com. `null` clears it.

Request body

{
  "brand_name": "Meridian Digital",
  "logo_url": "https://cdn.meridian.test/logo.png",
  "primary_color": "#7c3aed",
  "support_email": "help@meridian.test",
  "footer_text": "Reports by Meridian Digital",
  "hide_seentics": true,
  "slug": "meridian"
}

Response 200

{
  "data": {
    "brand_name": "Meridian Digital",
    "logo_url": "https://cdn.meridian.test/logo.png",
    "primary_color": "#7c3aed",
    "support_email": "help@meridian.test",
    "footer_text": "Reports by Meridian Digital",
    "hide_seentics": true,
    "slug": "meridian",
    "updated_at": "2026-10-12T10:00:00.000Z"
  }
}

curl

curl -X PUT "https://api.seentics.com/api/v1/agency/branding" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand_name":"Meridian Digital","logo_url":"https://cdn.meridian.test/logo.png","primary_color":"#7c3aed","support_email":"help@meridian.test","footer_text":"Reports by Meridian Digital","hide_seentics":true,"slug":"meridian"}'

GET/api/v1/agency/domain

Custom domain and its statedata is null when there is no domain; 503 provider_error when this server offers no custom domains.Scope agency:read

Response 200

{
  "data": {
    "hostname": "reports.meridian.test",
    "state": "pending_dns",
    "reason": null,
    "cname_target": "portal.seentics.com",
    "ownership_verification": {
      "name": "_cf-custom-hostname.reports.meridian.test",
      "type": "txt",
      "value": "7f3a9c1e-…"
    },
    "created_at": "2026-10-12T10:00:00.000Z",
    "updated_at": "2026-10-12T10:00:00.000Z",
    "last_checked_at": "2026-10-12T10:05:00.000Z"
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/domain" \
  -H "X-API-Key: $SEENTICS_API_KEY"

PUT/api/v1/agency/domain

Add or replace the custom domainScope agency:write

Body

Name	Type	Description
`hostname`required	string	A subdomain you control, e.g. reports.youragency.com.

Request body

{
  "hostname": "reports.meridian.test"
}

Response 200

{
  "data": {
    "hostname": "reports.meridian.test",
    "state": "pending_dns",
    "reason": null,
    "cname_target": "portal.seentics.com",
    "ownership_verification": {
      "name": "_cf-custom-hostname.reports.meridian.test",
      "type": "txt",
      "value": "7f3a9c1e-…"
    },
    "created_at": "2026-10-12T10:00:00.000Z",
    "updated_at": "2026-10-12T10:00:00.000Z",
    "last_checked_at": "2026-10-12T10:05:00.000Z"
  }
}

curl

curl -X PUT "https://api.seentics.com/api/v1/agency/domain" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"reports.meridian.test"}'

POST/api/v1/agency/domain/refresh

Check DNS and the certificate nowScope agency:write · send an Idempotency-Key

Response 200

{
  "data": {
    "hostname": "reports.meridian.test",
    "state": "pending_certificate",
    "reason": null,
    "cname_target": "portal.seentics.com",
    "ownership_verification": {
      "name": "_cf-custom-hostname.reports.meridian.test",
      "type": "txt",
      "value": "7f3a9c1e-…"
    },
    "created_at": "2026-10-12T10:00:00.000Z",
    "updated_at": "2026-10-12T10:00:00.000Z",
    "last_checked_at": "2026-10-12T10:05:00.000Z"
  }
}

curl

curl -X POST "https://api.seentics.com/api/v1/agency/domain/refresh" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

DELETE/api/v1/agency/domain

Remove the custom domainScope agency:write

Answers 204 with no body.

curl

curl -X DELETE "https://api.seentics.com/api/v1/agency/domain" \
  -H "X-API-Key: $SEENTICS_API_KEY"

Embeds

GET/api/v1/agency/embeds

List embed linksScope agency:read

Query

Name	Type	Description
`scope`	"website" \| "client"	Only links of this scope.
`target_id`	uuid	Only links for this website or client.
`limit`	integer	Up to 100 rows; default 25.
`cursor`	string	The `next_cursor` of the previous page.

Response 200

{
  "data": [
    {
      "id": "9a1f3c52-0d6e-4c1b-8b7e-2c4b3f0e1d77",
      "scope": "client",
      "target_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
      "target_name": "Acme Bakery",
      "token": "emb_4b7c0e9f2a",
      "embed_url": "https://seentics.com/embed/2f60eb30-722c-4fbf-8afa-99fe0e67f6d9?token=emb_4b7c0e9f2a&client=1",
      "sections": [
        "analytics"
      ],
      "created_at": "2026-10-12T10:00:00.000Z"
    }
  ],
  "page": {
    "next_cursor": null,
    "has_more": false
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/embeds?scope=client&target_id=5bbeaa88-b089-4923-ad54-8fdcbbcdba94" \
  -H "X-API-Key: $SEENTICS_API_KEY"

POST/api/v1/agency/embeds

Create an embed linkA read-only dashboard anyone with the link can open. 201 when made; 200 with the existing link when the target already has one.Scope agency:write · send an Idempotency-Key

Body

Name	Type	Description
`scope`required	"website" \| "client"	One website, or all of a client’s.
`target_id`required	uuid	The website or client.
`sections`	("analytics" \| "recordings" \| "heatmaps")[]	Default `["analytics"]`.

Request body

{
  "scope": "client",
  "target_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
  "sections": [
    "analytics"
  ]
}

Response 201

{
  "data": {
    "id": "9a1f3c52-0d6e-4c1b-8b7e-2c4b3f0e1d77",
    "scope": "client",
    "target_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
    "target_name": "Acme Bakery",
    "token": "emb_4b7c0e9f2a",
    "embed_url": "https://seentics.com/embed/2f60eb30-722c-4fbf-8afa-99fe0e67f6d9?token=emb_4b7c0e9f2a&client=1",
    "sections": [
      "analytics"
    ],
    "created_at": "2026-10-12T10:00:00.000Z"
  }
}

curl

curl -X POST "https://api.seentics.com/api/v1/agency/embeds" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"scope":"client","target_id":"5bbeaa88-b089-4923-ad54-8fdcbbcdba94","sections":["analytics"]}'

PATCH/api/v1/agency/embeds/:id

Change what an embed link showsScope agency:write

Path parameters

Name	Type	Description
`id`required	uuid	The embed link’s ID.

Body

Name	Type	Description
`sections`required	string[]	The sections to show.

Request body

{
  "sections": [
    "analytics",
    "heatmaps"
  ]
}

Response 200

{
  "data": {
    "id": "9a1f3c52-0d6e-4c1b-8b7e-2c4b3f0e1d77",
    "scope": "client",
    "target_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
    "target_name": "Acme Bakery",
    "token": "emb_4b7c0e9f2a",
    "embed_url": "https://seentics.com/embed/2f60eb30-722c-4fbf-8afa-99fe0e67f6d9?token=emb_4b7c0e9f2a&client=1",
    "sections": [
      "analytics",
      "heatmaps"
    ],
    "created_at": "2026-10-12T10:00:00.000Z"
  }
}

curl

curl -X PATCH "https://api.seentics.com/api/v1/agency/embeds/9a1f3c52-0d6e-4c1b-8b7e-2c4b3f0e1d77" \
  -H "X-API-Key: $SEENTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sections":["analytics","heatmaps"]}'

DELETE/api/v1/agency/embeds/:id

Revoke an embed linkCreating one again gives a new URL.Scope agency:write

Path parameters

Name	Type	Description
`id`required	uuid	The embed link’s ID.

Answers 204 with no body.

curl

curl -X DELETE "https://api.seentics.com/api/v1/agency/embeds/9a1f3c52-0d6e-4c1b-8b7e-2c4b3f0e1d77" \
  -H "X-API-Key: $SEENTICS_API_KEY"

Usage

GET/api/v1/agency/usage

This month’s pool, use, allocation and overageScope agency:read

Query

Name	Type	Description
`month`	string	`YYYY-MM`; default the current UTC month.

Response 200

{
  "data": {
    "period": {
      "start": "2026-10-01T00:00:00.000Z",
      "end": "2026-11-01T00:00:00.000Z"
    },
    "pool": {
      "events": 5000000,
      "recordings": 50000,
      "leads": 10000,
      "ai_analyses": 1000
    },
    "used": {
      "events": 1240512,
      "recordings": 8204,
      "leads": 312,
      "ai_analyses": 41
    },
    "allocated": {
      "events": 0,
      "recordings": 0,
      "leads": 0,
      "ai_analyses": 0
    },
    "unallocated": {
      "events": 5000000,
      "recordings": 50000,
      "leads": 10000,
      "ai_analyses": 1000
    },
    "overage": {
      "events": 0,
      "recordings": 0,
      "leads": 0,
      "ai_analyses": 0
    }
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/usage" \
  -H "X-API-Key: $SEENTICS_API_KEY"

GET/api/v1/agency/usage/clients

Use per client this monthScope agency:read

Query

Name	Type	Description
`month`	string	`YYYY-MM`; default the current UTC month.

Response 200

{
  "data": [
    {
      "id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
      "name": "Acme Bakery",
      "used": {
        "events": 412000,
        "recordings": 2100,
        "leads": 88,
        "ai_analyses": 12
      },
      "cap": {
        "events": null,
        "recordings": null,
        "leads": null,
        "ai_analyses": null
      },
      "pct": {
        "events": null,
        "recordings": null,
        "leads": null,
        "ai_analyses": null
      }
    }
  ],
  "page": {
    "next_cursor": null,
    "has_more": false
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/usage/clients" \
  -H "X-API-Key: $SEENTICS_API_KEY"

GET/api/v1/agency/usage/websites

Use per website this monthScope agency:read

Query

Name	Type	Description
`client_id`	uuid	Only this client’s websites.
`month`	string	`YYYY-MM`; default the current UTC month.

Response 200

{
  "data": [
    {
      "id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
      "name": "Acme Bakery",
      "used": {
        "events": 412000,
        "recordings": 2100,
        "leads": 88,
        "ai_analyses": 12
      },
      "cap": {
        "events": null,
        "recordings": null,
        "leads": null,
        "ai_analyses": null
      },
      "pct": {
        "events": null,
        "recordings": null,
        "leads": null,
        "ai_analyses": null
      },
      "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94"
    }
  ],
  "page": {
    "next_cursor": null,
    "has_more": false
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/usage/websites?client_id=5bbeaa88-b089-4923-ad54-8fdcbbcdba94" \
  -H "X-API-Key: $SEENTICS_API_KEY"

GET/api/v1/agency/clients/:id/usage

One client’s use this month, with its websitesScope agency:read

Path parameters

Name	Type	Description
`id`required	uuid	The client’s ID.

Query

Name	Type	Description
`month`	string	`YYYY-MM`; default the current UTC month.

Response 200

{
  "data": {
    "period": {
      "start": "2026-10-01T00:00:00.000Z",
      "end": "2026-11-01T00:00:00.000Z"
    },
    "id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94",
    "name": "Acme Bakery",
    "used": {
      "events": 412000,
      "recordings": 2100,
      "leads": 88,
      "ai_analyses": 12
    },
    "cap": {
      "events": null,
      "recordings": null,
      "leads": null,
      "ai_analyses": null
    },
    "pct": {
      "events": null,
      "recordings": null,
      "leads": null,
      "ai_analyses": null
    },
    "websites": [
      {
        "id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
        "name": "Acme Bakery",
        "used": {
          "events": 412000,
          "recordings": 2100,
          "leads": 88,
          "ai_analyses": 12
        },
        "cap": {
          "events": null,
          "recordings": null,
          "leads": null,
          "ai_analyses": null
        },
        "pct": {
          "events": null,
          "recordings": null,
          "leads": null,
          "ai_analyses": null
        },
        "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94"
      }
    ]
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/clients/5bbeaa88-b089-4923-ad54-8fdcbbcdba94/usage" \
  -H "X-API-Key: $SEENTICS_API_KEY"

GET/api/v1/agency/websites/:id/usage

One website’s use this monthScope agency:read

Path parameters

Name	Type	Description
`id`required	uuid	The website’s ID.

Query

Name	Type	Description
`month`	string	`YYYY-MM`; default the current UTC month.

Response 200

{
  "data": {
    "period": {
      "start": "2026-10-01T00:00:00.000Z",
      "end": "2026-11-01T00:00:00.000Z"
    },
    "id": "2f60eb30-722c-4fbf-8afa-99fe0e67f6d9",
    "name": "Acme Bakery",
    "used": {
      "events": 412000,
      "recordings": 2100,
      "leads": 88,
      "ai_analyses": 12
    },
    "cap": {
      "events": null,
      "recordings": null,
      "leads": null,
      "ai_analyses": null
    },
    "pct": {
      "events": null,
      "recordings": null,
      "leads": null,
      "ai_analyses": null
    },
    "client_id": "5bbeaa88-b089-4923-ad54-8fdcbbcdba94"
  }
}

curl

curl -X GET "https://api.seentics.com/api/v1/agency/websites/2f60eb30-722c-4fbf-8afa-99fe0e67f6d9/usage" \
  -H "X-API-Key: $SEENTICS_API_KEY"

Error codes

Status	Code	Meaning
`401`	`unauthorized`	No session or API key, or it is no longer valid.
`403`	`forbidden`	The key lacks the scope, or the team member lacks agency access.
`403`	`agency_plan_required`	The account is not on the Agency plan.
`404`	`not_found`	No such client, website, embed or alert in this account.
`422`	`validation_failed`	The body or query is invalid; `details` says which field.
`409`	`conflict`	Already exists, such as an external ID or hostname in use.
`409`	`idempotency_conflict`	The same Idempotency-Key was sent with a different body.
`429`	`rate_limited`	120 requests a minute per key (60 writes); wait and retry.
`502`	`provider_error`	Our DNS or certificate provider failed; retry later. 503 when the service, or custom domains, are not available.