SearchResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/influship-com/json-schema/influship-com-search-response-schema.json",
  "title": "SearchResponse",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/influship-com-openapi.json#/components/schemas/SearchResponse",
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/$defs/SearchResponseData"
    },
    "quality": {
      "description": "How results were ranked: all with AI relevance scoring, a mix of AI and discovery ranking, or discovery ranking throughout. When omitted, treat the response as `reranked`. Use each `match.ranking_source` to interpret its score.",
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "mode": {
              "type": "string",
              "const": "reranked"
            },
            "reason": {
              "type": "null"
            }
          },
          "required": [
            "mode",
            "reason"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "mode": {
              "type": "string",
              "const": "partially_reranked"
            },
            "reason": {
              "type": "string",
              "enum": [
                "content_policy",
                "incomplete_rerank_output",
                "partial_batch_failure",
                "provider_error",
                "soft_timeout"
              ]
            }
          },
          "required": [
            "mode",
            "reason"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "mode": {
              "type": "string",
              "const": "retrieval_fallback"
            },
            "reason": {
              "type": "string",
              "enum": [
                "content_policy",
                "incomplete_rerank_output",
                "partial_batch_failure",
                "provider_error",
                "soft_timeout"
              ]
            }
          },
          "required": [
            "mode",
            "reason"
          ],
          "additionalProperties": false
        }
      ],
      "type": "object"
    },
    "search_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Search ID. Use with GET /v1/search/{id} for free pagination."
    },
    "total": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Total number of results across all pages"
    },
    "has_more": {
      "type": "boolean",
      "description": "Whether more results are available"
    },
    "next_cursor": {
      "description": "Cursor for the next page",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "data",
    "search_id",
    "total",
    "has_more",
    "next_cursor"
  ],
  "additionalProperties": false,
  "$defs": {
    "CreatorBasic": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Creator unique identifier"
        },
        "name": {
          "type": "string",
          "description": "Creator display name"
        },
        "bio": {
          "description": "Creator bio",
          "type": [
            "string",
            "null"
          ]
        },
        "avatar_url": {
          "description": "Avatar URL",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "id",
        "name",
        "bio",
        "avatar_url"
      ],
      "additionalProperties": false,
      "description": "Basic creator information"
    },
    "MatchInfo": {
      "type": "object",
      "properties": {
        "score": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Match relevance score (0-1)"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Relevance value from 0 to 1. Mirrors `score`; interpret it using `ranking_source`."
        },
        "low_confidence": {
          "type": "boolean",
          "description": "True when `confidence` is at or below the low-confidence threshold. Use this flag to group candidates for additional review. It does not change which results are returned."
        },
        "ranking_source": {
          "description": "How this result was ranked: `reranked` uses AI relevance scoring; `retrieval_fallback` uses discovery ranking. When omitted, treat the result as `reranked`. Retrieval scores describe discovery relevance rather than campaign fit.",
          "type": "string",
          "enum": [
            "reranked",
            "retrieval_fallback"
          ]
        },
        "reasons": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Human-readable match reasons (plain text)."
        },
        "evidence": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/MatchReasonEvidence"
          },
          "description": "Evidence-grounded version of `reasons`, in the same order: each reason has a provenance label and, where it rests on a post, the backing `source_post_id` and a verbatim `evidence_quote`."
        }
      },
      "required": [
        "score",
        "confidence",
        "low_confidence",
        "reasons",
        "evidence"
      ],
      "additionalProperties": false,
      "description": "Search match information"
    },
    "MatchReasonEvidence": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "description": "Human-readable reason this creator matched."
        },
        "provenance": {
          "$ref": "#/$defs/ReasonProvenance"
        },
        "fact_id": {
          "description": "Stored profile fact backing this reason, or null.",
          "type": [
            "string",
            "null"
          ]
        },
        "source_post_id": {
          "description": "Identifier of the source post supporting this reason, or null for non-post-backed reasons. This identifier is not a public post URL.",
          "type": [
            "string",
            "null"
          ]
        },
        "evidence_quote": {
          "description": "Supporting text copied verbatim from a source post caption or transcript. Present for `post_evidence` reasons when a supporting quote is available; otherwise null.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "text",
        "provenance",
        "fact_id",
        "source_post_id",
        "evidence_quote"
      ],
      "additionalProperties": false,
      "description": "A single evidence-grounded match reason."
    },
    "Platform": {
      "type": "string",
      "enum": [
        "instagram"
      ],
      "description": "Social media platform"
    },
    "ProfileSummary": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Profile unique identifier"
        },
        "platform": {
          "$ref": "#/$defs/Platform"
        },
        "username": {
          "type": "string",
          "description": "Profile username"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Profile URL"
        },
        "followers": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ],
          "description": "Follower count (null if unknown)"
        },
        "engagement_rate": {
          "anyOf": [
            {
              "type": "number",
              "minimum": 0
            },
            {
              "type": "null"
            }
          ],
          "description": "Engagement rate as a percentage, null if unknown (e.g. 3.5 means 3.5%)"
        },
        "is_verified": {
          "type": "boolean",
          "description": "Whether the account is verified"
        },
        "data_updated_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
            },
            {
              "type": "null"
            }
          ],
          "description": "When the stored public profile data was last refreshed"
        }
      },
      "required": [
        "id",
        "platform",
        "username",
        "url",
        "followers",
        "engagement_rate",
        "is_verified",
        "data_updated_at"
      ],
      "additionalProperties": false,
      "description": "Abbreviated profile information"
    },
    "ReasonProvenance": {
      "type": "string",
      "enum": [
        "post_evidence",
        "profile_fact",
        "inferred"
      ],
      "description": "How grounded a match reason is, strongest first. `post_evidence`: backed by a specific source post, identified by `source_post_id` with supporting text in `evidence_quote`. `profile_fact`: backed by a profile fact without post evidence. `inferred`: model reasoning over the profile with no direct post evidence."
    },
    "SearchResponseData": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchResultItem"
      }
    },
    "SearchResultItem": {
      "type": "object",
      "properties": {
        "creator": {
          "$ref": "#/$defs/CreatorBasic"
        },
        "relevant_profile": {
          "anyOf": [
            {
              "$ref": "#/$defs/ProfileSummary"
            },
            {
              "type": "null"
            }
          ],
          "description": "Most relevant profile based on search query (null if no profile data available)"
        },
        "primary_profile": {
          "anyOf": [
            {
              "$ref": "#/$defs/ProfileSummary"
            },
            {
              "type": "null"
            }
          ],
          "description": "Primary profile (largest audience, null if no profile data available)"
        },
        "match": {
          "$ref": "#/$defs/MatchInfo"
        },
        "location_unverified": {
          "description": "True when the query required a country but this creator location is unverified; false when the known location satisfies it; null when the query set no geography requirement. Known mismatches are excluded from results.",
          "type": [
            "boolean",
            "null"
          ]
        }
      },
      "required": [
        "creator",
        "relevant_profile",
        "primary_profile",
        "match",
        "location_unverified"
      ],
      "additionalProperties": false
    }
  }
}