Skip to Content
API referenceSamplings

Samplings

Related events: sampling.completed · sampling.failed

Endpoints

The Sampling object

Attributes

  • idstring

    Unique identifier of the object (prefixed, opaque).

  • objectstring

    sampling

  • marketstring

    Market code (ISO country, e.g. FR).

  • triggerenum

    What started a sampling. onboarding is the first sampling of a brand, launched when the owner closes the stepper (day 0). targeted re-runs a single query from the query drawer — it always carries a prompt_id.

    Possible values: onboarding · scheduled · manual · targeted

  • statusenum

    Possible values: queued · running · completed · failed

  • querystringnullable
  • week_starts_onstring
  • modelsarray of object
  • queries_countinteger
  • runs_totalinteger
  • runs_completedinteger
  • runs_failedinteger
  • brand_shareobject

    Share (%) of the answers citing the brand — null until the sampling is finalized.

  • by_modelarray of object
    Show child attributes
    • modelstring
    • runsinteger
    • hitsinteger
    • avg_positionnumbernullable
  • errorstringnullable
  • started_atstringnullable
  • finished_atstringnullable
  • livemodeboolean

    true for live data, false for the test-mode sandbox.

  • createdinteger

    Time at which the object was created (unix timestamp, seconds).

The Sampling object
{
  "id": "smp_031DIivuBKog78mwjgnZUv",
  "object": "sampling",
  "market": "FR",
  "trigger": "scheduled",
  "status": "completed",
  "query": null,
  "week_starts_on": "2026-09-21",
  "models": [
    "chatgpt",
    "claude",
    "gemini",
    "perplexity"
  ],
  "queries_count": 40,
  "runs_total": 640,
  "runs_completed": 635,
  "runs_failed": 5,
  "brand_share": 31.9,
  "by_model": [
    {
      "model": "chatgpt",
      "runs": 160,
      "hits": 61,
      "avg_position": 2.4
    },
    {
      "model": "claude",
      "runs": 158,
      "hits": 49,
      "avg_position": 2.9
    },
    {
      "model": "gemini",
      "runs": 157,
      "hits": 38,
      "avg_position": 3.1
    },
    {
      "model": "perplexity",
      "runs": 160,
      "hits": 55,
      "avg_position": 2.2
    }
  ],
  "error": null,
  "started_at": "2026-09-21T02:00:04Z",
  "finished_at": "2026-09-21T02:41:37Z",
  "livemode": true,
  "created": 1790042400
}

Retrieve a sampling

GET/v1/brands/{brand}/samplings/{sampling}

Parameters

  • brandstringrequired

    Brand id (br_…).

  • samplingstringrequired

    Sampling id (smp_…).

Returns

Returns the sampling object. Raises an error if something goes wrong.

curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/samplings/smp_034EPf7p3si7LL82NkYBhb \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
Response
{
  "id": "smp_031DIivuBKog78mwjgnZUv",
  "object": "sampling",
  "market": "FR",
  "trigger": "scheduled",
  "status": "completed",
  "query": null,
  "week_starts_on": "2026-09-21",
  "models": [
    "chatgpt",
    "claude",
    "gemini",
    "perplexity"
  ],
  "queries_count": 40,
  "runs_total": 640,
  "runs_completed": 635,
  "runs_failed": 5,
  "brand_share": 31.9,
  "by_model": [
    {
      "model": "chatgpt",
      "runs": 160,
      "hits": 61,
      "avg_position": 2.4
    },
    {
      "model": "claude",
      "runs": 158,
      "hits": 49,
      "avg_position": 2.9
    },
    {
      "model": "gemini",
      "runs": 157,
      "hits": 38,
      "avg_position": 3.1
    },
    {
      "model": "perplexity",
      "runs": 160,
      "hits": 55,
      "avg_position": 2.2
    }
  ],
  "error": null,
  "started_at": "2026-09-21T02:00:04Z",
  "finished_at": "2026-09-21T02:41:37Z",
  "livemode": true,
  "created": 1790042400
}

List samplings

GET/v1/brands/{brand}/samplings

The measurements of the brand, newest first: the weekly samplings of each market and the targeted re-samplings of a single query.

Parameters

  • brandstringrequired

    Brand id (br_…).

  • marketstring
  • statusstring
  • limitinteger

    Number of objects to return, between 1 and 100 (default 20).

  • starting_afterstring

    Cursor: the id of the last object of the previous page.

Returns

A dictionary with a data property holding up to limit sampling objects, newest first, and has_more telling whether another page exists. Raises an error if something goes wrong.

curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/samplings?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
Response
{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/samplings",
  "has_more": false,
  "data": [
    {
      "id": "smp_031DIivuBKog78mwjgnZUv",
      "object": "sampling",
      "market": "FR",
      "trigger": "scheduled",
      "status": "completed",
      "query": null,
      "week_starts_on": "2026-09-21",
      "models": [
        "chatgpt",
        "claude",
        "gemini",
        "perplexity"
      ],
      "queries_count": 40,
      "runs_total": 640,
      "runs_completed": 635,
      "runs_failed": 5,
      "brand_share": 31.9,
      "by_model": [
        {
          "model": "chatgpt",
          "runs": 160,
          "hits": 61,
          "avg_position": 2.4
        },
        {
          "model": "claude",
          "runs": 158,
          "hits": 49,
          "avg_position": 2.9
        },
        {
          "model": "gemini",
          "runs": 157,
          "hits": 38,
          "avg_position": 3.1
        },
        {
          "model": "perplexity",
          "runs": 160,
          "hits": 55,
          "avg_position": 2.2
        }
      ],
      "error": null,
      "started_at": "2026-09-21T02:00:04Z",
      "finished_at": "2026-09-21T02:41:37Z",
      "livemode": true,
      "created": 1790042400
    }
  ]
}
Last updated on
RevenueTasks