Skip to content
Kindgi

Fetch the full provenance DAG for a run

View as Markdown
GET
/v1/provenance/{runId}
curl --request GET \
  --url https://example.com/v1/provenance/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Returns the full DAG (nodes + edges) plus record metadata: an agent turn’s record, or a flow run’s. A flow run’s record is written just after the run ends. From the run’s end until it is, the answer is 404 provenance-not-found with error.details.recordState: being-written; if writing it failed, recordState: failed and error.details.reason, a code. More states and codes may come. 404 with neither when the run has no record: a run still running, a dry run, an erased run, a run from before records were kept for it, or a deployment that doesn’t write them.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
runId
required
string format: uuid

RunId — opaque branded string (a UUID).

Responses

Section titled “Responses”

200

Section titled “200”

Full provenance record.

Media typeapplication/json

Full provenance record including the DAG payload.

object
id
required
string format: uuid
runId
required
string format: uuid
tenantId
required
string format: uuid
version
required
string
flowRef
object
id
required
string
version
required
string
dag
required
object
nodes
required
Array<object>
object
id
required
string
kind
required
string
Allowed values: input prompt retrieval tool-call tool-result model-call model-output artifact guardrail-check event policy-decision memory-read memory-write wait resume step
timestamp
required
string format: date-time
actor
string
contentHash
string
contentRef
string
modelVersion
string
policyDecisionId
string
attributes
object
key
additional properties
any
edges
required
Array<object>
object
from
required
string
to
required
string
kind
required
string
Allowed values: caused-by influenced-by retrieved-from invoked produced checked-against waited-on resumed-from
signature

Runtime-side signature attached at emission time (if the deployment signs on write). Independent of the export-time signature returned by the export route.

object
algorithm
required
string
Allowed value: ed25519
keyId
required
string
value
required

Base64-encoded signature bytes.

string
signedAt
required
string format: date-time
createdAt
required
string format: date-time
callUsage

Each model call’s usage from the cost ledger, by the callId in its model-call node’s attributes. Joined when read: not part of the signed DAG. A signed export includes it, as it stood when signed.

object
key
additional properties
object
usage
required

The call’s tokens. promptTokens / completionTokens are the totals; cacheReadTokens / cacheWriteTokens are parts of promptTokens, reasoningTokens of completionTokens, present when the provider reports them.

object
promptTokens
required
integer
completionTokens
required
integer
cacheReadTokens
integer
cacheWriteTokens
integer
reasoningTokens
integer
costUsd
number
durationMs
integer
servedModel
string
stepUsage

A flow record’s model usage per step, by the step node’s id: the model calls of the runs the step started (an agent step’s turn, a sub-flow’s run) and of the runs they started, from the cost ledger. A folded loop node sums its iterations’. A tool step’s own model calls, made by its pack with its own key, aren’t in it. Joined when read: not part of the signed DAG. A signed export includes it, as it stood when signed.

object
key
additional properties
object
calls
required
integer
costUsd
required
number
tokens
required
object
prompt
required
integer
completion
required
integer
cacheRead
required
integer
cacheWrite
required
integer
reasoning
required
integer
Example
{
  "dag": {
    "nodes": [
      {
        "kind": "input"
      }
    ],
    "edges": [
      {
        "kind": "caused-by"
      }
    ]
  },
  "signature": {
    "algorithm": "ed25519"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “404”

No provenance record for that run under this tenant (provenance-not-found; error.details.recordState says when it is still being written, or failed).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

503

Section titled “503”

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also