Pull (purchase) a process — batch size

Reveal the input/output exchanges (the 'batch size' / functional unit) of a process for one or more of its reference products. Wraps the same processes/pull-many flow used by the Process pull modal in app.circa.ai.

POST/public/processes/:id/pull

⚠

This endpoint is non-idempotent and billable. Each successful request debits credits per (process, referenceProduct) pair. Wrap it in your own idempotency layer if you're calling it from a retry-able workflow.

Pulling a process reveals its inputs and outputs arrays — the materials it consumes and produces, plus the value/unit that anchors any impact calculation (the batch size). Each process may have one or more reference products; you pay separately for each one you reveal.

To reveal impact values rather than the batch size, use POST /processes/:id/impacts/pull.

Path parameters

Parameter	Type	Description
idrequired	string (uuid)	The process id.

Request body

Parameter	Type	Description
referenceProductIdsrequired	string[]	1–500 reference-product ids on the process. Read the value from `process.referenceProductId` on GET /processes responses.

Response

200OK

{
  "processId": "bfffd26f-aa46-42ab-9069-e07102b06c4d",
  "pulledReferenceProductIds": ["f5651ee4-1234-4d1e-9b21-3a8e2c91c0a1"],
  "revealedCount": 1
}

revealedCountis how many (process, referenceProduct) pairs were newly revealed by this call — pairs already revealed for the team aren't re-debited. The server returns 409 if every requested pair was already revealed.

Errors

400Bad Request when referenceProductIds is empty or contains non-UUID values. 403Forbidden when the team has insufficient credits. 404Not Found when no requested pair matches a known process. 409Conflict when every requested pair is already revealed.

Example

curl -s -X POST \
  'https://api.circa.ai/public/processes/bfffd26f-aa46-42ab-9069-e07102b06c4d/pull' \
  -H 'x-api-key: circa_live_xxx' \
  -H 'x-team-id: TEAM_ID_FROM_OVERVIEW' \
  -H 'Circa-Version: 2026-05-11.arrakis' \
  -H 'Content-Type: application/json' \
  -d '{"referenceProductIds": ["f5651ee4-1234-4d1e-9b21-3a8e2c91c0a1"]}'

After pulling

On subsequent GET /processes/:id calls for this team, the process's inputs and outputsarrays will be fully populated with values and units. To list only processes you've pulled, call GET /processes?pulled=true.