Insights
Cedar's and Sequoia's insights on your vehicles and buy targets, as data, with what each rests on, how sure it is and the guardrail that applied.
TL;DRAI summary
This chapter explains how Cypress's smart advisors, Cedar and Sequoia, give you actionable insights on your vehicles and buy targets, such as pricing or next steps. You can access these insights through the API to help automate your operations.
Cypress's advisors already read every vehicle and every buy target in the app: Cedar says whether to sell or hold, where to price and whether a car is ready to market, and Sequoia suggests what to do next in your plan. The API returns the same insights as data, so your systems and agents can act on them. Since 1.5.0.
| Scope | Grants |
|---|---|
insights:read | GET /api/v1/insights, and include=insights on a single vehicle, listing or buy-target read |
insights:read is never a default scope. Both an API key and a Connect
Cypress token are accepted.
Ask
curl "$BASE/api/v1/insights?vehicleId=clx…" -H "authorization: Bearer $TOKEN"
curl "$BASE/api/v1/insights?targetId=clx…&kinds=buy-guide" -H "authorization: Bearer $TOKEN"What you get depends on whose record it is:
| You ask about | Kinds |
|---|---|
Your own vehicle (view: owner) | sell-hold (Cedar: sell, hold or review), pricing (Cedar: a suggested floor and target, days to sell, market position), campaign (Cedar: whether it is ready to market, likely buyers, channels), sequoia (Sequoia's live items on the car or its lot) |
Another organization's car on sale (view: buyer) | listing: the Marketplace's own listing insight, written from the asking price and public values |
| Your own buy target | buy-guide (the Buy plan's price guide, no model), sequoia (Sequoia's live items on the target) |
kinds narrows the list; a kind that does not apply to the record is left
out. Another organization's car that is not for sale, or its target, answers
404, exactly as an unknown id does.
The insight
{
"kind": "pricing",
"by": "cedar",
"summary": "Comparable RAV4s are moving at $24,500; a floor of $19,000 sells within three weeks.",
"confidence": { "score": null, "level": "HIGH" },
"basis": {
"facts": { "floorPrice": 20000, "targetPrice": 25000, "wholesale": 22000, "valuationDays": 3, "daysInState": 9, "status": "LISTED" },
"reasons": []
},
"guardrail": { "code": "BELOW_FLOOR", "words": "The suggested floor is below yours. It is advice only: Cypress never sells under the floor you set." },
"data": { "suggestedFloor": 19000, "suggestedTarget": 24500, "daysToSellEstimate": 18, "marketPosition": "FAIR" },
"generatedAt": "2026-10-15T14:00:00.000Z",
"cached": false
}basisis what the insight rests on: the facts it read and, for Sequoia's items, its reasons in words.confidenceis the writer's 0–100 score where it gives one, and a level.guardrailis the rule that bounded it:NO_VALUATION(no valuation yet),VALUATION_STALE(older than 14 days),BELOW_FLOOR(advice under your floor, which Cypress never sells under),TOO_FEW_SALES(too few sales from too few sellers to price a target), or one of Sequoia's (OFFER,PRICE_ABOVE_TARGET,BUDGET_SHARE,GOAL_CHANGE,SCHEDULE_CHANGE: a person decides).
Inline
Add include=insights to GET /api/v1/vehicles/{id}, GET /api/v1/listings/{id} or GET /api/v1/buy-planning/targets/{id} to get the
record's insights beside it (insights). It needs insights:read as well as
the read's own scope.
Cost and privacy
Cedar's insights each cost a model call, so an answer is kept for six hours,
keyed on everything it read: change the floor, or get a new valuation, and the
next request asks again (cached says which you got). A credential gets 30
insight requests a minute (429 RATE_LIMITED, Retry-After: 60), beside the
API's own limit.
A buyer's credential never receives a figure derived from a seller's floor: the owner's insights read its floor and target, so only the owner gets them. A price guide needs sales from at least two seller companies and five sales, or it gives no price; Sequoia's items on a target come in words, never with their raw numbers.
Events
INSIGHT.CREATED tells you when Sequoia puts a recommendation in front of your
organization, new or back after its answer ran out, with the insight as GET /api/v1/insights shows it and what it is about. It is opt-in and needs
insights:read: see Webhooks.