HTTP API reference

The Durable Functions extension exposes a set of built-in HTTP APIs that can be used to perform management tasks on orchestrations, entities, and task hubs. These HTTP APIs are extensibility webhooks that are authorized by the Azure Functions host but handled directly by the Durable Functions extension.

All HTTP APIs implemented by the extension require the following parameters. The data type of all parameters is string.

Parameter Parameter Type Description
taskHub Query string The name of the task hub. If not specified, the current function app's task hub name is assumed.
connection Query string The name of the connection string for the storage account. If not specified, the default connection string for the function app is assumed.
systemKey Query string The authorization key required to invoke the API.

systemKey is an authorization key autogenerated by the Azure Functions host. It specifically grants access to the Durable Task extension APIs and can be managed the same way as other authorization keys. You can generate URLs that contain the correct taskHub, connection, and systemKey query string values using orchestration client binding APIs, such as the CreateCheckStatusResponse and CreateHttpManagementPayload APIs in .NET, or the createCheckStatusResponse and createHttpManagementPayload APIs in JavaScript.

The next few sections cover the specific HTTP APIs supported by the extension and provide examples of how they can be used.

Start orchestration

Starts executing a new instance of the specified orchestrator function.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

POST /admin/extensions/DurableTaskExtension/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

POST /runtime/webhooks/durabletask/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
functionName URL The name of the orchestrator function to start.
instanceId URL Optional parameter. The ID of the orchestration instance. If not specified, the orchestrator function will start with a random instance ID.
{content} Request content Optional. The JSON-formatted orchestrator function input.

Response

Several possible status code values can be returned.

  • HTTP 202 (Accepted): The specified orchestrator function was scheduled to start running. The Location response header contains a URL for polling the orchestration status.
  • HTTP 400 (Bad request): The specified orchestrator function doesn't exist, the specified instance ID was not valid, or request content was not valid JSON.

The following is an example request that starts a RestartVMs orchestrator function and includes JSON object payload:

POST /runtime/webhooks/durabletask/orchestrators/RestartVMs?code=XXX
Content-Type: application/json
Content-Length: 83

{
    "resourceGroup": "myRG",
    "subscriptionId": "111deb5d-09df-4604-992e-a968345530a9"
}

The response payload for the HTTP 202 cases is a JSON object with the following fields:

Field Description
id The ID of the orchestration instance.
statusQueryGetUri The status URL of the orchestration instance.
sendEventPostUri The "raise event" URL of the orchestration instance.
terminatePostUri The "terminate" URL of the orchestration instance.
purgeHistoryDeleteUri The "purge history" URL of the orchestration instance.
rewindPostUri (preview) The "rewind" URL of the orchestration instance.

The data type of all fields is string.

Here is an example response payload for an orchestration instance with abc123 as its ID (formatted for readability):

{
    "id": "abc123",
    "purgeHistoryDeleteUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/raiseEvent/{eventName}?code=XXX",
    "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/terminate?reason={text}&code=XXX"
}

The http response is intended to be compatible with the Polling Consumer Pattern. It also includes the following notable response headers:

  • Location: The URL of the status endpoint. This URL contains the same value as the statusQueryGetUri field.
  • Retry-After: The number of seconds to wait between polling operations. The default value is 10.

For more information on the asynchronous HTTP polling pattern, see the HTTP async operation tracking documentation.

Get instance status

Gets the status of a specified orchestration instance.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

GET /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

GET /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
instanceId URL The ID of the orchestration instance.
showInput Query string Optional parameter. If set to false, the function input will not be included in the response payload.
showHistory Query string Optional parameter. If set to true, the orchestration execution history will be included in the response payload.
showHistoryOutput Query string Optional parameter. If set to true, the function outputs will be included in the orchestration execution history.
createdTimeFrom Query string Optional parameter. When specified, filters the list of returned instances that were created at or after the given ISO8601 timestamp.
createdTimeTo Query string Optional parameter. When specified, filters the list of returned instances that were created at or before the given ISO8601 timestamp.
runtimeStatus Query string Optional parameter. When specified, filters the list of returned instances based on their runtime status. To see the list of possible runtime status values, see the Querying instances article.

Response

Several possible status code values can be returned.

  • HTTP 200 (OK): The specified instance is in a completed state.
  • HTTP 202 (Accepted): The specified instance is in progress.
  • HTTP 400 (Bad Request): The specified instance failed or was terminated.
  • HTTP 404 (Not Found): The specified instance doesn't exist or has not started running.
  • HTTP 500 (Internal Server Error): The specified instance failed with an unhandled exception.

The response payload for the HTTP 200 and HTTP 202 cases is a JSON object with the following fields:

Field Data type Description
runtimeStatus string The runtime status of the instance. Values include Running, Pending, Failed, Canceled, Terminated, Completed.
input JSON The JSON data used to initialize the instance. This field is null if the showInput query string parameter is set to false.
customStatus JSON The JSON data used for custom orchestration status. This field is null if not set.
output JSON The JSON output of the instance. This field is null if the instance is not in a completed state.
createdTime string The time at which the instance was created. Uses ISO 8601 extended notation.
lastUpdatedTime string The time at which the instance last persisted. Uses ISO 8601 extended notation.
historyEvents JSON A JSON array containing the orchestration execution history. This field is null unless the showHistory query string parameter is set to true.

Here is an example response payload including the orchestration execution history and activity outputs (formatted for readability):

{
  "createdTime": "2018-02-28T05:18:49Z",
  "historyEvents": [
      {
          "EventType": "ExecutionStarted",
          "FunctionName": "E1_HelloSequence",
          "Timestamp": "2018-02-28T05:18:49.3452372Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Tokyo!",
          "ScheduledTime": "2018-02-28T05:18:51.3939873Z",
          "Timestamp": "2018-02-28T05:18:52.2895622Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Seattle!",
          "ScheduledTime": "2018-02-28T05:18:52.8755705Z",
          "Timestamp": "2018-02-28T05:18:53.1765771Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello London!",
          "ScheduledTime": "2018-02-28T05:18:53.5170791Z",
          "Timestamp": "2018-02-28T05:18:53.891081Z"
      },
      {
          "EventType": "ExecutionCompleted",
          "OrchestrationStatus": "Completed",
          "Result": [
              "Hello Tokyo!",
              "Hello Seattle!",
              "Hello London!"
          ],
          "Timestamp": "2018-02-28T05:18:54.3660895Z"
      }
  ],
  "input": null,
  "customStatus": { "nextActions": ["A", "B", "C"], "foo": 2 },
  "lastUpdatedTime": "2018-02-28T05:18:54Z",
  "output": [
      "Hello Tokyo!",
      "Hello Seattle!",
      "Hello London!"
  ],
  "runtimeStatus": "Completed"
}

The HTTP 202 response also includes a Location response header that references the same URL as the statusQueryGetUri field mentioned previously.

Get all instances status

You can also query the status of all instances by removing the instanceId from the 'Get instance status' request. In this case, the basic parameters are the same as the 'Get instance status'. Query string parameters for filtering are also supported.

One thing to remember is that connection and code are optional. If you have anonymous auth on the function, then code isn't required. If you don't want to use a different storage connection string other than defined in the AzureWebJobsStorage app setting, then you can safely ignore the connection query string parameter.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

GET /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &showInput=[true|false]
    &top={integer}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

GET /runtime/webhooks/durableTask/instances?
    taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &showInput=[true|false]
    &top={integer}

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
instanceId URL The ID of the orchestration instance.
showInput Query string Optional parameter. If set to false, the function input will not be included in the response payload.
showHistory Query string Optional parameter. If set to true, the orchestration execution history will be included in the response payload.
showHistoryOutput Query string Optional parameter. If set to true, the function outputs will be included in the orchestration execution history.
createdTimeFrom Query string Optional parameter. When specified, filters the list of returned instances that were created at or after the given ISO8601 timestamp.
createdTimeTo Query string Optional parameter. When specified, filters the list of returned instances that were created at or before the given ISO8601 timestamp.
runtimeStatus Query string Optional parameter. When specified, filters the list of returned instances based on their runtime status. To see the list of possible runtime status values, see the Querying instances article.
top Query string Optional parameter. When specified, limits the number of instances returned by the query.

Response

Here is an example of response payloads including the orchestration status (formatted for readability):

[
    {
        "instanceId": "7af46ff000564c65aafbfe99d07c32a5",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:39Z",
        "lastUpdatedTime": "2018-06-04T10:46:47Z"
    },
    {
        "instanceId": "80eb7dd5c22f4eeba9f42b062794321e",
        "runtimeStatus": "Running",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:28Z",
        "lastUpdatedTime": "2018-06-04T15:18:38Z"
    },
    {
        "instanceId": "9124518926db408ab8dfe84822aba2b1",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:54Z",
        "lastUpdatedTime": "2018-06-04T10:47:03Z"
    },
    {
        "instanceId": "d100b90b903c4009ba1a90868331b11b",
        "runtimeStatus": "Pending",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:39Z",
        "lastUpdatedTime": "2018-06-04T15:18:39Z"
    }
]

Note

This operation can be very expensive in terms of Azure Storage I/O if there are a lot of rows in the Instances table. More details on Instance table can be found in the Performance and scale in Durable Functions (Azure Functions) documentation.

If more results exist, a continuation token is returned in the response header. The name of the header is x-ms-continuation-token.

If you set continuation token value in the next request header, you can get the next page of results. This name of the request header is also x-ms-continuation-token.

Purge single instance history

Deletes the history and related artifacts for a specified orchestration instance.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

DELETE /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

DELETE /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
instanceId URL The ID of the orchestration instance.

Response

The following HTTP status code values can be returned.

  • HTTP 200 (OK): The instance history has been purged successfully.
  • HTTP 404 (Not Found): The specified instance doesn't exist.

The response payload for the HTTP 200 case is a JSON object with the following field:

Field Data type Description
instancesDeleted integer The number of instances deleted. For the single instance case, this value should always be 1.

Here is an example response payload (formatted for readability):

{
    "instancesDeleted": 1
}

Purge multiple instance histories

You can also delete the history and related artifacts for multiple instances within a task hub by removing the {instanceId} from the 'Purge single instance history' request. To selectively purge instance history, use the same filters described in the 'Get all instances status' request.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

DELETE /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

DELETE /runtime/webhooks/durabletask/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
createdTimeFrom Query string Filters the list of purged instances that were created at or after the given ISO8601 timestamp.
createdTimeTo Query string Optional parameter. When specified, filters the list of purged instances that were created at or before the given ISO8601 timestamp.
runtimeStatus Query string Optional parameter. When specified, filters the list of purged instances based on their runtime status. To see the list of possible runtime status values, see the Querying instances article.

Note

This operation can be very expensive in terms of Azure Storage I/O if there are a lot of rows in the Instances and/or History tables. More details on these tables can be found in the Performance and scale in Durable Functions (Azure Functions) documentation.

Response

The following HTTP status code values can be returned.

  • HTTP 200 (OK): The instance history has been purged successfully.
  • HTTP 404 (Not Found): No instances were found that match the filter expression.

The response payload for the HTTP 200 case is a JSON object with the following field:

Field Data type Description
instancesDeleted integer The number of instances deleted.

Here is an example response payload (formatted for readability):

{
    "instancesDeleted": 250
}

Raise event

Sends an event notification message to a running orchestration instance.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

POST /runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
instanceId URL The ID of the orchestration instance.
eventName URL The name of the event that the target orchestration instance is waiting on.
{content} Request content The JSON-formatted event payload.

Response

Several possible status code values can be returned.

  • HTTP 202 (Accepted): The raised event was accepted for processing.
  • HTTP 400 (Bad request): The request content was not of type application/json or was not valid JSON.
  • HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (Gone): The specified instance has completed or failed and cannot process any raised events.

Here is an example request that sends the JSON string "incr" to an instance waiting for an event named operation:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/raiseEvent/operation?taskHub=DurableFunctionsHub&connection=Storage&code=XXX
Content-Type: application/json
Content-Length: 6

"incr"

The responses for this API do not contain any content.

Terminate instance

Terminates a running orchestration instance.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

POST /runtime/webhooks/durabletask/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Request parameters for this API include the default set mentioned previously as well as the following unique parameter.

Field Parameter Type Description
instanceId URL The ID of the orchestration instance.
reason Query string Optional. The reason for terminating the orchestration instance.

Response

Several possible status code values can be returned.

  • HTTP 202 (Accepted): The terminate request was accepted for processing.
  • HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (Gone): The specified instance has completed or failed.

Here is an example request that terminates a running instance and specifies a reason of buggy:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/terminate?reason=buggy&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

The responses for this API do not contain any content.

Rewind instance (preview)

Restores a failed orchestration instance into a running state by replaying the most recent failed operations.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

POST /runtime/webhooks/durabletask/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Request parameters for this API include the default set mentioned previously as well as the following unique parameter.

Field Parameter Type Description
instanceId URL The ID of the orchestration instance.
reason Query string Optional. The reason for rewinding the orchestration instance.

Response

Several possible status code values can be returned.

  • HTTP 202 (Accepted): The rewind request was accepted for processing.
  • HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (Gone): The specified instance has completed or was terminated.

Here is an example request that rewinds a failed instance and specifies a reason of fixed:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/rewind?reason=fixed&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

The responses for this API do not contain any content.

Signal entity

Sends a one-way operation message to a Durable Entity. If the entity doesn't exist, it will be created automatically.

Note

Durable entities are available starting in Durable Functions 2.0.

Request

The HTTP request is formatted as follows (multiple lines are shown for clarity):

POST /runtime/webhooks/durabletask/entities/{entityType}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &op={operationName}

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
entityType URL The type of the entity.
entityKey URL The unique name of the entity.
op Query string Optional. The name of the user-defined operation to invoke.
{content} Request content The JSON-formatted event payload.

Here is an example request that sends a user-defined "Add" message to a Counter entity named steps. The content of the message is the value 5. If the entity does not already exist, it will be created by this request:

POST /runtime/webhooks/durabletask/entities/Counter/steps?op=Add
Content-Type: application/json

5

Response

This operation has several possible responses:

  • HTTP 202 (Accepted): The signal operation was accepted for asynchronous processing.
  • HTTP 400 (Bad request): The request content was not of type application/json, was not valid JSON, or had an invalid entityKey value.
  • HTTP 404 (Not Found): The specified entityType was not found.

A successful HTTP request does not contain any content in the response. A failed HTTP request may contain JSON-formatted error information in the response content.

Query entity

Gets the state of the specified entity.

Request

The HTTP request is formatted as follows (multiple lines are shown for clarity):

GET /runtime/webhooks/durabletask/entities/{entityType}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

Response

This operation has two possible responses:

  • HTTP 200 (OK): The specified entity exists.
  • HTTP 404 (Not Found): The specified entity was not found.

A successful response contains the JSON-serialized state of the entity as its content.

Example

The following example HTTP request gets the state of an existing Counter entity named steps:

GET /runtime/webhooks/durabletask/entities/Counter/steps

If the Counter entity simply contained a number of steps saved in a currentValue field, the response content might look like the following (formatted for readability):

{
    "currentValue": 5
}

Next steps