Docs / Reference / read: withheld

read: withheld.

Reads the withheld count for one brand or one tenant to The answer gives the count by buyer profile and temperature, with the period and the limit it was read against

Figure 1POST /v1/read/withheldspecified

The caller sends WithheldInput to /v1/read/withheld. The platform returns a card whose body is WithheldCount.

POST/v1/read/withheld

The withheld count. The call needs the brand rung under a token with the read grant, and it is served by the platform.

The route takes WithheldInput and returns a card whose body is WithheldCount.

Request body#

The request body is WithheldInput.

field	type	required
`brand`	`id`	no
`tenant`	`id`	no
`period`	Window	yes

Response#

The route returns a card whose body is WithheldCount. Every card ends with a foot that states the basis of each number, the scope of the call, and the time when the facts were true.

Headers#

header	required	meaning
`Scale-Scope`	yes	the scope the call runs in: tenant/, then /brand/, then /strategy/
`Scale-As-True-On`	no	the date the facts must have been true on; defaults to now
`Scale-As-Known-On`	no	the date the facts must have been known on; defaults to now
`Scale-Key`	no	for a change, the key made from the input; a repeat under the same key returns the unit held and writes nothing

A caller needs the brand rung and a token with the read grant. The platform serves this route.

Example#

The example sends the smallest body that WithheldInput allows. The build validates it against the schema of WithheldInput.

Example

curl -X POST https://api.scaleintelligence.co/v1/read/withheld \
  -H "Scale-Key: $SCALE_KEY" -H "Scale-Scope: tenant/<id>" \
  -H "content-type: application/json" \
  -d '{ "period": { "from": "…", "to": "…" } }'

import { client } from "@scale/sdk";
const answer = await client.read.withheld({
    "period": {
      "from": "…",
      "to": "…"
    }
  });
// answer.body is a WithheldCount. answer.foot holds the basis, the scope and the time.

import requests
answer = requests.post("https://api.scaleintelligence.co/v1/read/withheld",
    headers={"Scale-Key": KEY, "Scale-Scope": "tenant/<id>"},
    json={
      "period": {
        "from": "…",
        "to": "…"
      }
    }).json()

let answer: Card = client.post("https://api.scaleintelligence.co/v1/read/withheld")
    .header("Scale-Key", key).header("Scale-Scope", "tenant/<id>")
    .json(&WithheldInput { /* the fields of the page */ }).send().await?.json().await?;

MCP tool#

The MCP tool si.read.withheld takes the same input and returns the same card. The tool only reads data. An MCP host that renders cards draws this card from ui://scale-intelligence/cards/WithheldCount. The tool’s page describes it.

POST /v1/read/withheld
Scale-Scope: …
Scale-As-True-On: …
Scale-As-Known-On: …
Scale-Key: …
content-type: application/json

{
  "period": {
    "from": "…",
    "to": "…"
  }
}

Without a key, this page shows the request only. The request body is WithheldInput, and the route returns a card whose body is WithheldCount.

Claims#

claim	state	route or tool
The platform serves the route /v1/read/withheld at contract 0476e35e6e275db5.	target	`/v1/read/withheld`