---
title: "work: build facet"
description: "a facet kind, a seed (a predicate, a list of communities, or a place from the gazetteer), the scope, and the positive and negative controls to the facet's register with every candidate kept or dropped and its reason in words, its people, its pairs and its trend, and the facet not ready until its calibration is read"
section: reference
address: /reference/work/build_facet
contract: 0476e35e6e275db5
---
# work: build facet
a facet kind, a seed (a predicate, a list of communities, or a place from the gazetteer), the scope, and the positive and negative controls to the facet's register with every candidate kept or dropped and its reason in words, its people, its pairs and its trend, and the facet not ready until its calibration is read
[figure: The caller sends BuildFacetInput to /v1/work/build_facet. The platform returns a card whose body is Facet.]
POST/v1/work/build_faceta task, 202
Build a facet. The call needs the strategy rung under a token with the work grant, and it is served by either, by the size bound.
The route takes [BuildFacetInput](/concepts/buildfacetinput) and returns a card whose body is [Facet](/concepts/facet).
## Request body
The request body is [BuildFacetInput](/concepts/buildfacetinput).
| field | type | required | note |
|---|---|---|---|
| `facet_kind` | [FacetKind](/concepts/facetkind) | yes | |
| `seed` | `text` | yes | |
| `again` | `bool` | no | when true, the same seed is built again as new work, for a presence that changed since the last build; without it the same seed under the same measure is the same work and returns the run already made |
| `asked_again_at` | `time` | no | set by the tool from the ask, so the run's key differs; never typed by hand |
| `scope` | [Scope](/concepts/scope) | yes | |
## Response
The route returns a card whose body is [Facet](/concepts/facet). 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. This route runs as a long step and returns a task with status 202. `POST /v1/work/status` returns the task's progress, and `POST /v1/work/cancel` stops the task.
## 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 strategy rung and a token with the work grant. The platform or the desktop app serves this route.
## Example
The example sends the smallest body that BuildFacetInput allows. The build validates it against the schema of BuildFacetInput.
Example
```sh
curl -X POST https://api.scaleintelligence.co/v1/work/build_facet \
-H "Scale-Key: $SCALE_KEY" -H "Scale-Scope: tenant/" \
-H "content-type: application/json" \
-d '{ "facet_kind": "…", "seed": "…", "scope": { "level": "shared" } }'
```
```typescript
import { client } from "@scale/sdk";
const answer = await client.work.build_facet({
"facet_kind": "…",
"seed": "…",
"scope": {
"level": "shared"
}
});
// answer.body is a Facet. answer.foot holds the basis, the scope and the time.
```
```python
import requests
answer = requests.post("https://api.scaleintelligence.co/v1/work/build_facet",
headers={"Scale-Key": KEY, "Scale-Scope": "tenant/"},
json={
"facet_kind": "…",
"seed": "…",
"scope": {
"level": "shared"
}
}).json()
```
```rust
let answer: Card = client.post("https://api.scaleintelligence.co/v1/work/build_facet")
.header("Scale-Key", key).header("Scale-Scope", "tenant/")
.json(&BuildFacetInput { /* the fields of the page */ }).send().await?.json().await?;
```