Finish or terminate a run

POST

/v1/runs/{id}/events

curl --request POST \
  --url https://beta-api.plune.ai/v1/runs/example/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "event": "finish", "reason": "example" }'

• beta
• production
• local

The run lifecycle. finish freezes the summary and closes the run to new results; terminate closes it with a reason and can be reopened by joining the same key again. A repeated finish is an idempotent success — the CI step that sends it may itself be retried. Terminating an already finished run is the one refusal: its summary may already have gated a release.

Authorizations

• bearerAuth
• cookieAuth

Parameters

Path Parameters

id

required

string

Request Body ^required

Media type application/json

object

event

required

string

Allowed values: finish terminate

reason

string

<= 1024 characters

Responses

200

The run, and its summary if it just finished

Media type application/json

object

run

required

object

id

string

projectId

string

kind

string

Allowed values: automated manual mixed eval

externalKey

string

nullable

statusEvent

The value rerun is reached only by joining a terminated run again — it is never requested.

string

Allowed values: launched finished terminated rerun

configuration

What the run expects to happen. Without it, a crashed shard is indistinguishable from a green run.

object

expected

required

Array<object>

<= 10000 items

object

testCaseId

string

externalKey

object

key

additional properties

any

matrix

object

key

additional properties

Array<string>

meta

object

sha

string

branch

string

ciUrl

string format: uri

runner

string

title

What to call this run in a list. The first shard to declare one wins; a shard that arrives later fills a field left empty rather than overwriting.

string

>= 1 characters <= 200 characters

environment

Where it ran — staging, prod, a preview. Filterable on GET /v1/runs, so two CI matrices read as two histories.

string

>= 1 characters <= 64 characters

labels

How the run is marked — smoke, nightly, a team name. An empty array is how every mark is removed.

Array<string>

<= 32 items

startedAt

string

finishedAt

string

nullable

terminateReason

string

nullable

summary

What a run amounted to, frozen at finish. Distinct from RunSummary, which is the list-item shape.

object

counts

required

One entry per status that occurred; an absent key means zero.

object

key

additional properties

integer

notRun

required

Expected and never reported — what keeps a dead shard from looking green.

Array<string>

total

required

integer

summary

What a run amounted to, frozen at finish. Distinct from RunSummary, which is the list-item shape.

object

counts

required

One entry per status that occurred; an absent key means zero.

object

key

additional properties

integer

notRun

required

Expected and never reported — what keeps a dead shard from looking green.

Array<string>

total

required

integer

Example

{
  "run": {
    "kind": "automated",
    "statusEvent": "launched"
  }
}

400

Not a known event

Media type application/json

object

error

required

string

Example ^generated

{
  "error": "example"
}

401

No / invalid token or session

404

Not found or not yours

Media type application/json

object

error

required

string

Example ^generated

{
  "error": "example"
}

409

The event does not apply from this state; the body names what does

Media type application/json

object

error

required

string

from

required

string

event

required

string

allowed

required

What WOULD apply from this state. A CI script needs this to stop retrying.

Array<string>

Example ^generated

{
  "error": "example",
  "from": "example",
  "event": "example",
  "allowed": [
    "example"
  ]
}

429

Rate limited