Match Reasons

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

Match Reasons

Every scored result includes human-readable reasons explaining why a creator was returned. These reasons help you validate results, build trustworthy UIs, and debug queries that aren’t landing.

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 — new — 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
          }
        ]
      }
    }
  ]
}

reasons (plain strings) is unchanged and still supported. evidence is the same reasons in a structured form — reach for it when you want to show a buyer why to trust a match, not just that it scored well.

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 post you can open	source_post_id (fetch it via GET /v1/posts/{id}) and, when a genuinely supporting sentence exists, a verbatim evidence_quote from that post’s caption or transcript
profile_fact	Backed by a stored profile fact, but with no clickable source post	fact_id, no source_post_id
inferred	Model reasoning over the profile, no direct post evidence	text only

The evidence_quote is the sentence from the source post that best supports the reason, copied verbatim — never model-generated, so it can’t be a fabricated citation. When no sentence in the post actually supports the claim, the quote is omitted (null) and you still get the clickable source_post_id. Treat profile_fact as weaker than post_evidence (there’s nothing to click through to) and inferred as the softest signal — style them accordingly.

Confidence and the weak tail

confidence mirrors score (0–1). low_confidence is true when a result falls in the weak tail of the ranking — a non-breaking marker so you can draw a “weaker matches” divider instead of presenting every returned creator as an equally strong match. It never changes which results are returned; it only labels them.

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 audience demographics",
          "Comparable engagement patterns on workout videos"
        ]
      }
    }
  ]
}

Typical themes: content overlap, audience similarity, style, and performance 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",
            "evidence_quote": "This bar packs 20g of protein and actually tastes like dessert…"
          }
        ]
      }
    }
  ]
}

Decision	Meaning
good	Strong fit for the campaign
neutral	Could work — review manually
avoid	Weak fit, likely not worth pursuing

Campaign-match reasons carry the same provenance label as search evidence (post_evidence, profile_fact, inferred). When present, source_post_id points at a post you can open via GET /v1/posts/{id}, and evidence_quote is a verbatim snippet from that post. The fact_id is an internal reference to the supporting data point — use source_post_id and evidence_quote for anything user-facing.

How to Use Reasons

• Surface them in your UI. Reasons make AI-driven results feel transparent. Showing “Strong sustainable fashion focus” next to a creator helps your users trust the ranking.
• 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.