List demand signals
Demand signals pushed for the workspace, newest first, a page at a time. Add genus to see one genus, and current=true as well to get its current demand as a single reading; that answer is never paged, and meta.next_cursor is always null.
https://app.xplantpro.com/read:tasksQuery parameters
| Name | Type | Required | Description |
|---|---|---|---|
genus | string | No | Only signals for this genus. |
current | "true" | No | With genus, return the genus's current demand as a single reading instead of its history. |
limit | integer | No | Page size. Values above 200 are capped at 200. Default 50. From 1 to 200. |
offset | integer | No | Number of records to skip. Prefer cursor where a list offers it: an offset shifts when records are added ahead of it. Default 0. At least 0. |
cursor | string | No | Continue from the previous page: pass its meta.next_cursor unchanged, with the same filters. Treat it as opaque. Not combinable with offset. Up to 2048 characters. |
Example
curl "https://app.xplantpro.com/api/v1/tasks/demand?genus=Alocasia¤t=true" \
-H "Authorization: Bearer $XPLANT_API_KEY"Response
200 with { "ok": true, "data": … }. data is an array. To get the next page, pass meta.next_cursor back as cursor; it is null on the last page. See Pagination.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The signal's id — or current on the reading current=true returns. |
genus | string | Yes | — |
source_type | string | null | Yes | — |
demand_score | number | Yes | — |
source | string | Yes | — |
observed_at | string | Yes | — |
created_at | string | Yes | — |
{
"ok": true,
"data": [
{
"id": "c41e8a07-93d2-4b6f-8e15-7a2d0f9b3c58",
"genus": "Alocasia",
"source_type": "tissue",
"demand_score": 42,
"source": "storefront",
"observed_at": "2026-09-24T00:00:00.000Z",
"created_at": "2026-09-24T00:05:11.000Z"
}
]
}The envelope can also carry meta:
| Field | Type | Required | Description |
|---|---|---|---|
next_cursor | string | null | Yes | Pass as cursor to fetch the next page. null means this is the last page. |
| Response header | Meaning |
|---|---|
X-Request-Id | Identifies this request. Include it when you contact support. |
Errors
| Status | Code | When |
|---|---|---|
401 | UNAUTHORIZED | The key is missing, malformed or revoked, or its owner is no longer a member of the workspace. |
402 | PAID_PLAN_REQUIRED | The workspace's plan does not include the API. The full API is included with xPlant+ Teams and Enterprise; on Hobby and Pro Lab, keys can connect devices only. |
403 | FORBIDDEN | The key lacks a scope this operation requires, or its owner's current role in the workspace cannot use it — a key never does more than its owner can in xPlant. error names the scope, and for a role, the role it needs. |
403 | DEVICE_TOKEN_NOT_ACCEPTED | A device token was sent; this operation needs a workspace API key. |
422 | VALIDATION_ERROR | Both cursor and offset were sent; use one. |
422 | INVALID_CURSOR | The cursor is malformed, or came from a different list or different filters. Start again without it. |
429 | RATE_LIMIT_EXCEEDED | Too many requests for this key, device token or workspace. Wait Retry-After seconds. |
500 | DEMAND_QUERY_FAILED | The signals could not be read. Retry later. |
Branch on code, never on the error text. See Errors.
Update a task
Changes only the fields you send. Move a task along the board with workflow_status; complete it with "done".
Record a demand signal
Records how much demand there is for a genus — orders, sales velocity, a forecast — from any source you run. xPlant uses the latest signal per genus when it scores the task queue. Send one whenever your number changes; history is kept.