Campaign Fit & Evidence

Understand the AI explanations returned by search, lookalike, and match endpoints

Scored results include reasons you can use to review matches, explain rankings to your users, and refine queries.

​

Where Reasons Appear

Endpoint	Field	What it explains
POST /v1/search	data[].match.reasons	Why the creator matches your query
POST /v1/creators/lookalike	data[].similarity.shared_traits	Why the creator is similar to the seed
POST /v1/creators/match	data[].match.reasons	Why the creator is a good, neutral, or poor fit for the campaign

​

Search Reasons

Search results include a score, a plain-text reasons list, and a structured evidence array that grounds each reason, plus a confidence value and a low_confidence marker:

{
  "data": [
    {
      "creator": {
        "id": "a3f1b9c2-d4e5-6f7a-8b9c-0d1e2f3a4b5c",
        "name": "Nadia Kaur"
      },
      "match": {
        "score": 0.92,
        "confidence": 0.92,
        "low_confidence": false,
        "reasons": [
          "Publishes ingredient-education Reels on sensitive-skin routines",
          "High engagement rate suggests an active audience"
        ],
        "evidence": [
          {
            "text": "Publishes ingredient-education Reels on sensitive-skin routines",
            "provenance": "post_evidence",
            "fact_id": "b7c1f0a2-3d4e-5f60-8a9b-0c1d2e3f4a5b",
            "source_post_id": "23256c2e-51fa-4389-a4a1-945e461e951b",
            "evidence_quote": "Today we break down why fragrance wrecks a sensitive-skin barrier…"
          },
          {
            "text": "High engagement rate suggests an active audience",
            "provenance": "inferred",
            "fact_id": null,
            "source_post_id": null,
            "evidence_quote": null
          }
        ]
      }
    }
  ]
}

Use reasons for plain-text explanations and evidence for the same reasons with source details you can display alongside each match.

​

Provenance

Every entry in evidence carries a provenance label so you can tell a grounded claim from an inference. Strongest first:

provenance	Meaning	What you get
post_evidence	Backed by a specific source post	source_post_id identifies the source; evidence_quote contains supporting text when available
profile_fact	Backed by a profile fact	fact_id, no source_post_id
inferred	Inferred from profile information, without direct post evidence	text only

An evidence_quote contains supporting text copied verbatim from a source post. It is null when a supporting quote is unavailable; source_post_id is still returned when available. Display the quote and provenance together so users can distinguish post evidence, profile facts, and inferred reasons. Source IDs are identifiers, not public post URLs; do not construct a link from the ID.

​

Review lower-confidence matches

confidence mirrors score (0–1). Use match.ranking_source to interpret it: reranked indicates AI relevance scoring, while retrieval_fallback indicates discovery ranking. See search quality. When low_confidence is true, group the result under a label such as “Additional candidates to review.” This flag labels results without changing which creators are returned.

​

Lookalike Reasons

Lookalike results explain shared traits between the seed creator and the match:

{
  "data": [
    {
      "creator": {
        "id": "e8d7c6b5-a4f3-2e1d-0c9b-8a7f6e5d4c3b",
        "name": "Marcus Rivera"
      },
      "similarity": {
        "score": 0.87,
        "shared_traits": [
          "Both focus on fitness and wellness content",
          "Similar step-by-step presentation style",
          "Comparable engagement patterns on workout videos"
        ]
      }
    }
  ]
}

Shared traits describe content topics, presentation style, and posting or engagement patterns.

​

Campaign Match Reasons

POST /v1/creators/match returns structured campaign-fit output with a decision and supporting reasons:

{
  "data": [
    {
      "creator": {
        "id": "f9e8d7c6-b5a4-3f2e-1d0c-9b8a7f6e5d4c"
      },
      "match": {
        "score": 0.88,
        "decision": "good",
        "reasons": [
          {
            "text": "Reviews protein bars and macro-friendly snacks in weekly Reels",
            "provenance": "post_evidence",
            "fact_id": "fact_abc123",
            "source_post_id": "9b8a7f6e-5d4c-3b2a-1f0e-9d8c7b6a5f4e",
            "source_post_url": "https://www.instagram.com/p/C8xYz123AbC/",
            "evidence_quote": "This bar packs 20g of protein and actually tastes like dessert…"
          }
        ]
      }
    }
  ]
}

Decision	Score	Meaning
good	0.70 and above	Strong fit for the campaign
neutral	0.50 to 0.69	Could work — review manually
avoid	Below 0.50	Weak fit against the campaign brief

For every analyzed creator, the decision follows the score bands above, so decision and score never disagree. Unanalyzed placeholders (below) are the one exception.

Campaign-match reasons carry the same provenance label as search evidence (post_evidence, profile_fact, inferred). When present, source_post_id identifies the source post, source_post_url links to that post on its platform, and evidence_quote contains a verbatim snippet. Show the quote and provenance to your users, and use source_post_url when you want a click-through. source_post_url is omitted when no public link is available; source_post_id and fact_id are identifiers, not URLs. Every analyzed creator has at least one reason.

​

Creators that could not be analyzed

Occasionally a creator in a match request cannot be analyzed. The response still includes it, but its match carries "analysis_unavailable": true with a score of 0 and a neutral decision. Treat it as “no decision yet” rather than a real neutral: these placeholders are not charged API credits (x402 payments are priced per requested creator up front and are not refunded), and retrying the request (or just that creator) usually returns a full analysis. Analyzed creators omit the field.

Each creator appears at most once, even if you send it twice (for example by ID and by username). Creators that can’t be found or aren’t available for matching are left out of the response rather than returned as placeholders.

{
  "match": {
    "score": 0,
    "decision": "neutral",
    "analysis_unavailable": true,
    "reasons": [
      { "text": "Match analysis unavailable for this creator.", "provenance": "inferred" }
    ]
  }
}

​

How to Use Reasons

• Display reasons alongside scores. A reason such as “Publishes sustainable fashion content” gives users a concrete detail to review.
• Validate your queries. If the reasons don’t match your intent, the query needs refining — tighten the language or add filters.
• Compare across results. Reasons help you understand why one creator ranked higher than another, beyond just the numeric score.
• Debug broad searches. When results feel off, the reasons usually reveal whether the query was too vague or the filters too loose.

​

Scores vs Reasons

Treat the score as the summary and the reasons as the explanation. A high score with reasons that don’t match your intent is a signal to refine the query, not to trust the number.