explainBidScore

Requires permission biddesk:bid:read.

Asks Bid Desk AI to explain the bid's current score in two to four sentences. A check refuses any sentence that names a factor or a number the breakdown does not contain; then the status is UNAVAILABLE and nothing is shown. An unchanged score reuses its earlier explanation. Needs the Bid Desk AI plan feature. Requires Bid Desk and permission to read bids.

Errors: a failed call returns a GraphQL errors entry, not a field on the result, and data may be null or partial. Read the entry's extensions.code and message; every shape and code is in the Error reference.

Example:

GraphQL

mutation ExplainBidScore($bidId: ID!) {
  explainBidScore(bidId: $bidId) {
    code
    status
    createdAt
    model
    runId
    sentences {
      factors
      text
    }
  }
}

cURL

curl -X POST "https://<api-host>/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data @- <<'EOF'
{
  "query": "mutation ExplainBidScore($bidId: ID!) {\n  explainBidScore(bidId: $bidId) {\n    code\n    status\n    createdAt\n    model\n    runId\n    sentences {\n      factors\n      text\n    }\n  }\n}",
  "variables": {
    "bidId": "id"
  }
}
EOF

Variables:

{
  "bidId": "id"
}

Response:

{
  "data": {
    "explainBidScore": {
      "code": "string",
      "status": "READY",
      "createdAt": "2025-01-15T00:00:00Z",
      "model": "string",
      "runId": "id",
      "sentences": [
        {
          "factors": [
            "CUSTOMER_WIN_RATE"
          ],
          "text": "string"
        }
      ]
    }
  }
}

explainBidScore(
  bidId: ID!
): BidScoreExplanation!

Arguments

explainBidScore.bidId ● ID! non-null scalar

The bid.

Type

BidScoreExplanation object

A short AI explanation of the score in words. It only restates the breakdown; it never decides.