Send run heartbeat

http
POST /runs/{run_id}/heartbeats

Renew the execution lease of the current run generation.

Servers

json
[
  {
    "url": "https://api.veryfront.com"
  }
]

Authentication

json
[
  {
    "runExecutionAuth": []
  }
]
json
{
  "runExecutionAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT",
    "description": "Server-issued credential bound to project, run, registered runtime, execution generation, audience, expiry, and explicitly allowed operations; user/API-key editor access is insufficient."
  }
}

Parameters

NameLocationRequiredDescription
run_idpathYes
x-veryfront-run-credential-rotationheaderNoOpt in to atomic replacement of all five exact-child credentials on successful inherited heartbeat.
x-veryfront-run-dispatch-acceptanceheaderNoAtomically accept this detached dispatch before starting execution. A duplicate returns 409.

Parameter contracts

json
[
  {
    "schema": {
      "type": "string",
      "format": "uuid"
    },
    "required": true,
    "example": "11111111-1111-4111-8111-111111111111",
    "name": "run_id",
    "in": "path"
  },
  {
    "schema": {
      "type": "string",
      "enum": [
        "v2"
      ]
    },
    "required": false,
    "description": "Opt in to atomic replacement of all five exact-child credentials on successful inherited heartbeat.",
    "name": "x-veryfront-run-credential-rotation",
    "in": "header"
  },
  {
    "schema": {
      "type": "string",
      "enum": [
        "true"
      ]
    },
    "required": false,
    "description": "Atomically accept this detached dispatch before starting execution. A duplicate returns 409.",
    "name": "x-veryfront-run-dispatch-acceptance",
    "in": "header"
  }
]

Request body

json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CreateRunHeartbeatRequest"
      },
      "examples": {
        "minimal": {
          "summary": "Renew with default duration",
          "value": {}
        },
        "renew": {
          "summary": "Renew execution authority",
          "value": {
            "lease_duration_seconds": 60
          }
        }
      }
    }
  }
}

Responses

200

Execution lease renewed

json
{
  "description": "Execution lease renewed",
  "headers": {
    "X-Veryfront-Run-Credential-Rotation": {
      "description": "Present with all five replacement credentials after negotiated inherited v2 rotation.",
      "schema": {
        "type": "string",
        "enum": [
          "v2"
        ]
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/RunHeartbeat"
      },
      "examples": {
        "minimal": {
          "summary": "Renew with default duration",
          "value": {
            "run_id": "11111111-1111-4111-8111-111111111111",
            "expires_at": "2026-10-02T10:01:00Z"
          }
        },
        "renew": {
          "summary": "Renew execution authority",
          "value": {
            "run_id": "11111111-1111-4111-8111-111111111111",
            "expires_at": "2026-10-02T10:01:00Z"
          }
        }
      }
    }
  }
}

400

Bad request

json
{
  "description": "Bad request",
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 400
              }
            }
          }
        ]
      }
    }
  }
}

401

Unauthorized

json
{
  "description": "Unauthorized",
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 401
              }
            }
          }
        ]
      }
    }
  }
}

403

Forbidden

json
{
  "description": "Forbidden",
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 403
              }
            }
          }
        ]
      }
    }
  }
}

404

Not found

json
{
  "description": "Not found",
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 404
              }
            }
          }
        ]
      }
    }
  }
}

409

Conflict

json
{
  "description": "Conflict",
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 409
              }
            }
          }
        ]
      }
    }
  }
}

413

Payload too large

json
{
  "description": "Payload too large",
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 413
              }
            }
          }
        ]
      }
    }
  }
}

429

Rate limit exceeded

json
{
  "description": "Rate limit exceeded",
  "headers": {
    "Retry-After": {
      "schema": {
        "type": "integer",
        "format": "int32",
        "minimum": 1
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 429
              }
            }
          }
        ]
      }
    }
  }
}

Referenced contracts

components/schemas/CreateRunHeartbeatRequest

json
{
  "type": "object",
  "properties": {
    "lease_duration_seconds": {
      "type": "integer",
      "minimum": 5,
      "maximum": 300,
      "default": 60
    }
  },
  "additionalProperties": false
}

components/schemas/RunHeartbeat

json
{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string",
      "format": "uuid"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "run_id",
    "expires_at"
  ]
}

components/schemas/TargetRunProblem

json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "Problem type URI reference."
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 400,
      "maximum": 599,
      "format": "int64"
    },
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "cause": {
      "type": "string",
      "enum": [
        "schedule_concurrency_forbidden",
        "schedule_fire_in_progress",
        "schedule_run_limit_reached"
      ],
      "description": "Schedule admission refusal."
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "field",
          "message"
        ]
      }
    }
  },
  "required": [
    "type",
    "title",
    "status",
    "code"
  ]
}

Operation contract

json
{
  "operationId": "createRunHeartbeat",
  "tags": [
    "execution/Runs/Runtime"
  ],
  "security": [
    {
      "runExecutionAuth": []
    }
  ],
  "summary": "Send run heartbeat",
  "description": "Renew the execution lease of the current run generation.",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "example": "11111111-1111-4111-8111-111111111111",
      "name": "run_id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "v2"
        ]
      },
      "required": false,
      "description": "Opt in to atomic replacement of all five exact-child credentials on successful inherited heartbeat.",
      "name": "x-veryfront-run-credential-rotation",
      "in": "header"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true"
        ]
      },
      "required": false,
      "description": "Atomically accept this detached dispatch before starting execution. A duplicate returns 409.",
      "name": "x-veryfront-run-dispatch-acceptance",
      "in": "header"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateRunHeartbeatRequest"
        },
        "examples": {
          "minimal": {
            "summary": "Renew with default duration",
            "value": {}
          },
          "renew": {
            "summary": "Renew execution authority",
            "value": {
              "lease_duration_seconds": 60
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Execution lease renewed",
      "headers": {
        "X-Veryfront-Run-Credential-Rotation": {
          "description": "Present with all five replacement credentials after negotiated inherited v2 rotation.",
          "schema": {
            "type": "string",
            "enum": [
              "v2"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RunHeartbeat"
          },
          "examples": {
            "minimal": {
              "summary": "Renew with default duration",
              "value": {
                "run_id": "11111111-1111-4111-8111-111111111111",
                "expires_at": "2026-10-02T10:01:00Z"
              }
            },
            "renew": {
              "summary": "Renew execution authority",
              "value": {
                "run_id": "11111111-1111-4111-8111-111111111111",
                "expires_at": "2026-10-02T10:01:00Z"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Bad request",
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 400
                  }
                }
              }
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 401
                  }
                }
              }
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 403
                  }
                }
              }
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 404
                  }
                }
              }
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 409
                  }
                }
              }
            ]
          }
        }
      }
    },
    "413": {
      "description": "Payload too large",
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 413
                  }
                }
              }
            ]
          }
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded",
      "headers": {
        "Retry-After": {
          "schema": {
            "type": "integer",
            "format": "int32",
            "minimum": 1
          }
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 429
                  }
                }
              }
            ]
          }
        }
      }
    }
  },
  "x-codeSamples": [
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "minimal",
      "contentType": "application/json",
      "source": "{}"
    },
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "renew",
      "contentType": "application/json",
      "source": "{\n  \"lease_duration_seconds\": 60\n}"
    }
  ],
  "x-documentation-source-tag": "Runtime",
  "x-canonical-documentation": {
    "domain": "execution",
    "resource": "Runs",
    "subgroup": "Runtime",
    "name": "Send run heartbeat",
    "description": "Renew the execution lease of the current run generation.",
    "operationId": "createRunHeartbeat"
  },
  "x-mint": {
    "href": "/cloud/rest/api-reference/execution-runs-runtime/send-run-heartbeat"
  }
}