Skip to Content
Référence APISamplings

Samplings

Events associés : sampling.completed · sampling.failed

Endpoints

L’objet Sampling

Attributs

  • idstring

    Identifiant unique de l'objet (préfixé, opaque).

  • objectstring

    sampling

  • marketstring

    Code du marché (pays ISO, par ex. 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.

    Valeurs possibles : onboarding · scheduled · manual · targeted

  • statusenum

    Valeurs possibles : 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
    Afficher les attributs enfants
    • modelstring
    • runsinteger
    • hitsinteger
    • avg_positionnumbernullable
  • errorstringnullable
  • started_atstringnullable
  • finished_atstringnullable
  • livemodeboolean

    true pour les données réelles, false pour le bac à sable du mode test.

  • createdinteger

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

L'objet Sampling
{
  "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}

Paramètres

  • brandstringobligatoire

    Brand id (br_…).

  • samplingstringobligatoire

    Sampling id (smp_…).

Retour

Renvoie l’objet sampling. Lève une erreur en cas de problème.

curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/samplings/smp_034EPf7p3si7LL82NkYBhb \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
Réponse
{
  "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.

Paramètres

  • brandstringobligatoire

    Brand id (br_…).

  • marketstring
  • statusstring
  • limitinteger

    Nombre d'objets à renvoyer, entre 1 et 100 (20 par défaut).

  • starting_afterstring

    Curseur : l'id du dernier objet de la page précédente.

Retour

Un dictionnaire dont la propriété data contient jusqu’à limit objets sampling, du plus récent au plus ancien, et has_more indique s’il reste une page. Lève une erreur en cas de problème.

curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/samplings?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
Réponse
{
  "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