Skip to content
Plune Plune Plune Docs

The numbers of a draft widget

POST
/v1/widgets/data
 
curl --request POST \
  --url https://beta-api.plune.ai/v1/widgets/data \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "config": { "schemaVersion": 1, "render": "line", "bucket": "day", "accumulated": false, "blocks": [ { "entity": "run", "metric": "count", "filters": [ { "property": "kind", "values": [ "automated" ] } ] }, { "entity": "run_result", "metric": "count", "filters": [ { "property": "status", "values": [ "failed", "broken" ] } ] } ], "segment": { "by": "label", "values": [ "nightly" ] } }, "from": "2026-10-01T00:00:00Z", "to": "2026-10-03T23:59:59Z", "tz": "Europe/Kyiv" }'

The numbers of a recipe that is not saved, so the builder can redraw as the person configures. Judged exactly as a saved widget: the closed catalogue, the caps, the cost guard BEFORE any query (400 widget_too_expensive), a denominator on every block. Nothing is stored. It is a POST because the recipe is the body.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
config
required

The whole recipe of a widget; the server judges it on every write and every draft. Entities: case, run_result, run, requirement (a defect is not one yet). Properties come from a closed catalogue: a case has type, state, priority, suite, is_flaky, is_muted, tag; a result status, sub_status, source, muted, case_priority, environment, label; a run kind, environment, status_event, label; a requirement type, status, priority, category. A donut takes one block. A segment is cut across all blocks and only by a property they all have (label for runs and results; any groupable property for a single entity). Limits: 5 blocks, 10 segment values, 10 filters a block, 16 KiB.

object
schemaVersion
required
integer
Allowed values: 1
render
required
string
Allowed values: bar line donut table
bucket
string
default: day
Allowed values: day week month
accumulated

Line only: the population at each moment. For run_result and run (they only arrive); a case, a requirement and a defect wait.

boolean
blocks
required
Array<object>
>= 1 items <= 5 items
object
entity
required
string
Allowed values: case run_result run requirement
metric

A duration only for run_result and run.

string
default: count
Allowed values: count duration_sum duration_avg
filters
Array<object>
<= 10 items
object
property
required
string
values
required
Array<string>
>= 1 items <= 50 items
groupBy

A groupable property of the entity. More than 20 groups: the rest is folded into «Other» with a true sum.

string
segment
object
by
required
string
values
required
Array<string>
>= 1 items <= 10 items
from
required

ISO 8601 with a time zone. Both bounds are required: a widget has no «all time».

string format: date-time
to
required
string format: date-time
tz

The reader’s time zone, like Europe/Kyiv; the buckets are its calendar days, weeks (Monday) or months. Default UTC.

string
Example 
{
  "config": {
    "schemaVersion": 1,
    "render": "line",
    "bucket": "day",
    "accumulated": false,
    "blocks": [
      {
        "entity": "run",
        "metric": "count",
        "filters": [
          {
            "property": "kind",
            "values": [
              "automated"
            ]
          }
        ]
      },
      {
        "entity": "run_result",
        "metric": "count",
        "filters": [
          {
            "property": "status",
            "values": [
              "failed",
              "broken"
            ]
          }
        ]
      }
    ],
    "segment": {
      "by": "label",
      "values": [
        "nightly"
      ]
    }
  },
  "from": "2026-10-01T00:00:00Z",
  "to": "2026-10-03T23:59:59Z",
  "tz": "Europe/Kyiv"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The numbers

Media type application/json

The numbers of a widget. Every block shares one time axis; every block carries its denominator.

object
render
required
string
Allowed values: bar line donut table
bucket
required
string
Allowed values: day week month
from
required
string format: date-time
to
required
string format: date-time
axis
required

The start of each bucket, as a calendar date in the reader’s zone; at most 366.

Array<string>
series
required

At most 50 (blocks x groups x segment values), the biggest first when cut; empty for a table.

Array<object>
object
block
required
integer
entity
required
string
Allowed values: case run_result run requirement
group
required

null: no value of the grouped property, or no Group by.

string
nullable
segment
required
string
nullable
total
required

Over the whole period: what a donut slice or a table row shows.

number
nullable
points
required
Array<object>
object
t
required
string
v
required
number
nullable
rows

A table’s rows, at most 500.

Array<object>
object
block
required
integer
entity
required
string
group
required
string
nullable
segment
required
string
nullable
value
required
number
nullable
denominators
required

A6: per block, how many objects of the entity the project has in the period BEFORE the filters (denominator) and after them (matched). null for a block that ran out of time.

Array<object>
object
block
required
integer
entity
required
string
denominator
required
integer
nullable
matched
required
integer
nullable
truncated
required

Series or rows were dropped to hold the caps.

boolean
notMeasured
required

What could not be measured or shown whole, as codes: truncated_series, truncated_rows, folded_groups, block_timeout.

Array<object>
object
code
required
string
Allowed values: truncated_series truncated_rows folded_groups block_timeout
block
integer
params
object
key
additional properties
number
Example 
{
  "render": "line",
  "bucket": "day",
  "from": "2026-10-01T00:00:00.000Z",
  "to": "2026-10-03T23:59:59.000Z",
  "axis": [
    "2026-10-01",
    "2026-10-02",
    "2026-10-03"
  ],
  "series": [
    {
      "block": 0,
      "entity": "run",
      "group": null,
      "segment": "nightly",
      "total": 2,
      "points": [
        {
          "t": "2026-10-01",
          "v": 1
        },
        {
          "t": "2026-10-02",
          "v": 1
        },
        {
          "t": "2026-10-03",
          "v": 0
        }
      ]
    },
    {
      "block": 1,
      "entity": "run_result",
      "group": null,
      "segment": "nightly",
      "total": 3,
      "points": [
        {
          "t": "2026-10-01",
          "v": 0
        },
        {
          "t": "2026-10-02",
          "v": 3
        },
        {
          "t": "2026-10-03",
          "v": 0
        }
      ]
    }
  ],
  "denominators": [
    {
      "block": 0,
      "entity": "run",
      "denominator": 5,
      "matched": 2
    },
    {
      "block": 1,
      "entity": "run_result",
      "denominator": 120,
      "matched": 3
    }
  ],
  "truncated": false,
  "notMeasured": []
}

400

Section titled “400 ”

Invalid recipe or window, a window over 366 points, or over the cost budget (a code and its params say which)

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

401

Section titled “401 ”

No / invalid token or session

403

Section titled “403 ”

A read-only member

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

429

Section titled “429 ”

Rate-limited: the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442; the body names the plan, #2092). Retry-After carries the seconds until the window rolls over.

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

Headers

Section titled “Headers ”
Retry-After
integer

Seconds until the window rolls over