Endpoints
Get fork progress
Poll a fork batch for snapshot readiness and ordered child creation results.
GET
/
forks
/
{id}
curl --request GET \
--url "https://api.bead.run/forks/$FORK_ID" \
--header "X-API-Key: $BEAD_API_KEY"
{
"operationID": "<string>",
"snapshotID": "<string>",
"capture": {
"sourcePreserved": true,
"sourceBilling": "<string>",
"capturedAtMs": 123,
"freezeNanos": 123,
"sourceResumed": true,
"timing": {
"incremental": true,
"dirtyMemoryBytes": 123,
"totalNanos": 123,
"pauseNanos": 123,
"dumpNanos": 123,
"diskReflinkNanos": 123,
"adoptNanos": 123,
"cleanupNanos": 123,
"resumeNanos": 123,
"publicationNanos": 123
}
},
"status": "<string>",
"results": [
{
"index": 123,
"status": 123,
"operationID": "<string>",
"response": {
"alias": "<string>",
"clientID": "<string>",
"domain": {},
"envdAccessToken": "<string>",
"envdVersion": "<string>",
"grace_deadline": {},
"idle_timeout": {},
"kind": "<string>",
"last_activity": {},
"machine_state": "<string>",
"paused_at": {},
"sandboxID": "<string>",
"templateID": "<string>",
"trafficAccessToken": {},
"wake_reason": {},
"warnings": [
{}
],
"code": 123,
"message": "<string>",
"error_code": "<string>",
"limit": {
"limit": "<string>",
"maximum": 123,
"usage": 123,
"next_action": "<string>",
"reset_at": 123
},
"operationID": "<string>",
"status": "<string>"
}
}
]
}Authentication
Send your scoped bearer token in theAuthorization: Bearer <BEAD_TOKEN> header, or send your API key in X-API-Key.
Parameters
string
required
UUID of the fork batch. Format:
uuid.curl --request GET \
--url "https://api.bead.run/forks/$FORK_ID" \
--header "X-API-Key: $BEAD_API_KEY"
Response
202
Fork capture or one or more children are pending.string
required
Fork batch UUID to poll.
string
required
Snapshot shared by the fork children.
object | null
required
Memory capture result and source recovery details. May be
null.Show Properties
Show Properties
boolean
required
Whether the source was preserved for recovery.
string
required
Who pays for the source after capture. Allowed values:
"platform", "tenant".integer
required
Capture timestamp in Unix milliseconds.
integer
required
Source freeze duration in nanoseconds.
boolean
required
Whether the source resumed after capture.
object
required
Time spent in each capture stage.
Show Properties
Show Properties
boolean
required
Whether this capture used an incremental memory dump.
integer
required
Allocated memory dump bytes before flattening.
integer
required
Total capture time in nanoseconds.
integer
required
Pause time in nanoseconds.
integer
required
Memory dump time in nanoseconds.
integer
required
Disk clone time in nanoseconds.
integer
required
Snapshot adoption time in nanoseconds.
integer
required
Cleanup time in nanoseconds.
integer
required
Source resume time in nanoseconds.
integer
required
Publication time in nanoseconds.
string
required
Whether any children are still pending. Allowed values:
"pending", "completed".object[]
required
Ordered child results; a failed child has its own error response.
Show Properties
Show Properties
integer
required
Zero-based request index.
integer
required
HTTP status for this member; 202 means it is still pending.
string
Operation UUID for a pending member.
object
Machine connection fields on success, or an error body on failure. Accepts
object or object or object.Show Properties
Show Properties
string
Alias of the template
string
deprecated
Identifier of the client
string | null
Base domain where the sandbox traffic is accessible May be
null.string
Access token used for envd communication
string
Version of the envd running in the sandbox
string | null
End of the credit grace period as an RFC 3339 timestamp, or null when funded. May be
null.integer | string | null
Seconds without activity before a persistent machine pauses, or never to disable idle pause. Persistent machines default to 900 seconds; numeric values must be 300–86400. May be
null. Accepts integer or string (“never”).string
Lifetime policy: temporary expires at its timeout; persistent retains state until explicit deletion or the end of credit grace. Allowed values:
"temporary", "persistent".string | null
Most recent activity as an RFC 3339 timestamp, or null when no activity was recorded. May be
null.string
Current lifecycle state including running, idle-paused, waking, credit-grace, lost, or deleted. Allowed values:
"running", "idle-paused", "waking", "credit-grace", "lost", "deleted".string | null
Time the machine last paused as an RFC 3339 timestamp, or null when it has not paused. May be
null.string
Identifier of the sandbox
string
Identifier of the template from which is the sandbox created
string | null
Token required for accessing sandbox via proxy. May be
null.string | null
Reason for the last wake or lifecycle transition, or null when none is recorded. May be
null.object[]
Lifecycle or credit grace warnings attached to this machine. Additional keys accept
any values.integer
HTTP status code.
string
Explanation of the failed request.
string
Stable error identifier when supplied; use it to decide how to recover.
object
The resource limit that blocked the request.
string
Operation UUID.
string
Current operation state.
207
All child attempts finished; inspect each member status. The response fields are the same as the success body above.Errors
| Status | Meaning |
|---|---|
| 400 | Invalid resource UUID or request parameters. |
| 401 | Authentication credential is missing or rejected. |
| 403 | The credential lacks the required scope. |
| 404 | The requested resource does not exist or is outside your organization. |
| 429 | Request or resource admission limit exceeded (admission_limit). Follow limit.next_action and Retry-After when present. |
| 503 | Service or persistence is temporarily unavailable. |
⌘I
curl --request GET \
--url "https://api.bead.run/forks/$FORK_ID" \
--header "X-API-Key: $BEAD_API_KEY"
{
"operationID": "<string>",
"snapshotID": "<string>",
"capture": {
"sourcePreserved": true,
"sourceBilling": "<string>",
"capturedAtMs": 123,
"freezeNanos": 123,
"sourceResumed": true,
"timing": {
"incremental": true,
"dirtyMemoryBytes": 123,
"totalNanos": 123,
"pauseNanos": 123,
"dumpNanos": 123,
"diskReflinkNanos": 123,
"adoptNanos": 123,
"cleanupNanos": 123,
"resumeNanos": 123,
"publicationNanos": 123
}
},
"status": "<string>",
"results": [
{
"index": 123,
"status": 123,
"operationID": "<string>",
"response": {
"alias": "<string>",
"clientID": "<string>",
"domain": {},
"envdAccessToken": "<string>",
"envdVersion": "<string>",
"grace_deadline": {},
"idle_timeout": {},
"kind": "<string>",
"last_activity": {},
"machine_state": "<string>",
"paused_at": {},
"sandboxID": "<string>",
"templateID": "<string>",
"trafficAccessToken": {},
"wake_reason": {},
"warnings": [
{}
],
"code": 123,
"message": "<string>",
"error_code": "<string>",
"limit": {
"limit": "<string>",
"maximum": 123,
"usage": 123,
"next_action": "<string>",
"reset_at": 123
},
"operationID": "<string>",
"status": "<string>"
}
}
]
}