Running Workflows

Running workflows

`POST /workflows/{workflow_permanent_id}/run`

You can see the generic endpoint definition below. We’ll go into the specifics of the invoice retrieval workflow in the next section.

Body

Parameter	Type	Required?	Sample Value	Description
data	JSON	no	{ “website_url”: “YOUR_URL”, “invoice_retrieval_start_date”: “2024-04-15” },	The data field is used to pass in required and optional parameters that a workflow accepts. For the invoice retrieval workflow, required fields are website_url and invoice_retrieval_start_date
webhook_callback_url	String	no	…	Our system will send the webhook once it is finished executing the workflow run.
proxy_location	String	no	RESIDENTIAL	Proxy location for the web browser. Please pass RESIDENTIAL. If we use residential proxies, Skyvern’s requests to the websites will be less suspicious.

Response

Parameter	Type	Always returned?	Sample Value	Description
workflow_permanent_id	String	yes	wpid_123456	The workflow id
workflow_run_id	String	yes	wr_123456	The workflow run id that represents this specific workflow run. You can use this id to match the webhook response to the initial request.

Sample Request & Response - Invoice retrieval

$ -- Sample Request
> curl --location 'https://api.skyvern.com/api/v1/workflows/wpid_123456/run' \
> --header 'x-api-key: <USE_YOUR_API_KEY>' \
> --header 'Content-Type: application/json' \
> --data '{
>     "data": {
>         "website_url": "your_website",
>         "invoice_retrieval_start_date": "2024-04-15"
>     },
>     "proxy_location": "RESIDENTIAL",
>     "webhook_callback_url": "<your-endpoint>"
> }'
> 
> -- Sample Response
> {
>     "workflow_id": "wpid_123456",
>     "workflow_run_id": "wr_123456"
> }

Retrieving workflow runs

`GET /workflows/runs/{workflow_run_id}`

Response

Parameter	Type	Sample value	Description
workflow_id	String	wpid_123456
workflow_run_id	String	wr_123456
status	String	completed	Status of the workflow run. Possible values: created, running, failed, terminated, completed
proxy_location	JSON	RESIDENTIAL
webhook_callback_url	String	127.0.0.1:8000/api/v1/webhook
created_at	Timestamp	2024-05-16T08:35:24.920793	Timestamp for when the workflow run is created
modified_at	Timestamp	2024-05-16T08:42:32.568908	Last modified timestamp for the workflow run
parameters	JSON	see sample response below	The parameters that the workflow run was triggered with. For the invoice retrieval workflow, this field will have the website_url and invoice_retrieval_start_date values you sent.
screenshot_urls	list[String]	see sample response below	Final screenshots for the last 3 tasks in the workflow.
recording_url	String	see sample response below	The full browser recording.
outputs	JSON	see sample response below	See the explaining outputs section

Sample response

1 {
2     "workflow_id": "wpid_123456",
3     "workflow_run_id": "wr_123456",
4     "status": "completed",
5     "proxy_location": "RESIDENTIAL",
6     "webhook_callback_url": "127.0.0.1:8000/api/v1/webhook",
7     "created_at": "2024-05-16T08:35:24.920793",
8     "modified_at": "2024-05-16T08:42:32.568908",
9     "parameters": {
10         "website_url": "YOUR_WEBSITE_URL",
11         "invoice_retrieval_start_date": "2024-04-15"
12     },
13     "screenshot_urls": [
14         "https://skyvern-artifacts.s3.amazonaws.com/...",
15         "https://skyvern-artifacts.s3.amazonaws.com/...",
16         "https://skyvern-artifacts.s3.amazonaws.com/..."
17     ],
18     "recording_url": "https://skyvern-artifacts.s3.amazonaws.com/...",
19     "outputs": {
20         "login_output": {
21             "task_id": "tsk_1234",
22             "status": "completed",
23             "extracted_information": null,
24             "failure_reason": null,
25             "errors": []
26         },
27         "get_order_history_page_url_and_qualifying_order_ids_output": {
28             "task_id": "tsk_258409009008559418",
29             "status": "completed",
30             "extracted_information": {
31               ...
32             },
33             "failure_reason": null,
34             "errors": []
35         },
36         "iterate_over_order_ids_output": [
37             [
38                 {
39                     ...
40                 }
41             ]
42         ],
43         "download_invoice_for_order_output": {
44             "task_id": "tsk_258409361195877732",
45             "status": "completed",
46             "extracted_information": null,
47             "failure_reason": null,
48             "errors": []
49         },
50         "upload_downloaded_files_to_s3_output": [
51             "s3://skyvern-uploads/..."
52         ],
53         "send_email_output": {
54             "success": true
55         }
56     }
57 }

Webhooks

Skyvern always sends webhooks when a workflow run is executed. The status for an executed workflow run can be: completed, failed, terminated.

The webhook body is the same as the get workflow run endpoint.

Webhook Headers

Parameter	Type	Required?	Sample Value	Description
x-skyvern-signature	String	yes	v0=a2114d57b48eac39b9ad189dd8316235a7b4a8d21a10bd27519666489c69b503	Authentication token that allows our service to communicate with your backend service via callback / webhook We’ll be using the same strategy slack uses, as defined here: https://api.slack.com/authentication/verifying-requests-from-slack#making__validating-a-request
x-skyvern-timestamp	String	yes	1531420618	Timestamp used to decode and validate the incoming webhook call

We’ll be using the same strategy slack uses, as defined here: https://api.slack.com/authentication/verifying-requests-from-slack#making__validating-a-request |

Explaining `outputs`

If you checked out the sample response, you probably thought “What the heck is this field right here?”.

We previously went over that workflows are essentially a list of building blocks. outputs field has the output for every single block that a workflow has. Before we start analyzing the outputs from the sample above, let’s go over the building blocks for the invoice retrieval workflow.

Building blocks of invoice retrieval workflow:

#	Block type	Block label	Purpose
1	TaskBlock	login	Find login page, login to the website
2	TaskBlock	get_order_history_page_url_and_qualifying_order_ids	Find the order history page, extract order history page url, contact emails, and order details for orders after the start date
3	ForLoopBlock	iterate_over_order_ids	The contents of the ForLoop is executed for each order id that’s extracted from the previous step.
4	TaskBlock [within ForLoopBlock]	download_invoice_for_order	For a given order id, find a way to download the invoice, download it.
5	UploadToS3Block	upload_downloaded_files_to_s3	Upload all downloaded invoices to S3
6	SendEmailBlock	send_email	Send an email attaching all the downloaded invoices

⚠️ Still in development, not a blocker

The blocks within the ForLoop show up twice: within the ForLoop output and as a root block.
UploadToS3Block output is S3 URIs at the moment. They’ll be updated with signed urls instead.
Add block type to each object in outputs, define the output structure for each block for easier integration.

1 ...
2 "outputs": {
3     "login_output": {
4         "task_id": "tsk_1234",
5         "status": "completed",
6         "extracted_information": null,
7         "failure_reason": null,
8         "errors": []
9     },
10     "get_order_history_page_url_and_qualifying_order_ids_output": {
11         "task_id": "tsk_1234",
12         "status": "completed",
13         "extracted_information": {
14             ...
15         },
16         "failure_reason": null,
17         "errors": []
18     },
19     "iterate_over_order_ids_output": [
20         ...
21     ],
22     "download_invoice_for_order_output": {
23         "task_id": "tsk_1234",
24         "status": "completed",
25         "extracted_information": null,
26         "failure_reason": null,
27         "errors": []
28     },
29     "upload_downloaded_files_to_s3_output": [
30         "s3://skyvern-uploads/...",
31         "s3://skyvern-uploads/..."
32     ],
33     "send_email_output": {
34         "success": true
35     }
36 }
37 ...

$	-- Sample Request
>	curl --location 'https://api.skyvern.com/api/v1/workflows/wpid_123456/run' \
>	--header 'x-api-key: <USE_YOUR_API_KEY>' \
>	--header 'Content-Type: application/json' \
>	--data '{
>	"data": {
>	"website_url": "your_website",
>	"invoice_retrieval_start_date": "2024-04-15"
>	},
>	"proxy_location": "RESIDENTIAL",
>	"webhook_callback_url": "<your-endpoint>"
>	}'
>
>	-- Sample Response
>	{
>	"workflow_id": "wpid_123456",
>	"workflow_run_id": "wr_123456"
>	}

1	{
2	"workflow_id": "wpid_123456",
3	"workflow_run_id": "wr_123456",
4	"status": "completed",
5	"proxy_location": "RESIDENTIAL",
6	"webhook_callback_url": "127.0.0.1:8000/api/v1/webhook",
7	"created_at": "2024-05-16T08:35:24.920793",
8	"modified_at": "2024-05-16T08:42:32.568908",
9	"parameters": {
10	"website_url": "YOUR_WEBSITE_URL",
11	"invoice_retrieval_start_date": "2024-04-15"
12	},
13	"screenshot_urls": [
14	"https://skyvern-artifacts.s3.amazonaws.com/...",
15	"https://skyvern-artifacts.s3.amazonaws.com/...",
16	"https://skyvern-artifacts.s3.amazonaws.com/..."
17	],
18	"recording_url": "https://skyvern-artifacts.s3.amazonaws.com/...",
19	"outputs": {
20	"login_output": {
21	"task_id": "tsk_1234",
22	"status": "completed",
23	"extracted_information": null,
24	"failure_reason": null,
25	"errors": []
26	},
27	"get_order_history_page_url_and_qualifying_order_ids_output": {
28	"task_id": "tsk_258409009008559418",
29	"status": "completed",
30	"extracted_information": {
31	...
32	},
33	"failure_reason": null,
34	"errors": []
35	},
36	"iterate_over_order_ids_output": [
37	[
38	{
39	...
40	}
41	]
42	],
43	"download_invoice_for_order_output": {
44	"task_id": "tsk_258409361195877732",
45	"status": "completed",
46	"extracted_information": null,
47	"failure_reason": null,
48	"errors": []
49	},
50	"upload_downloaded_files_to_s3_output": [
51	"s3://skyvern-uploads/..."
52	],
53	"send_email_output": {
54	"success": true
55	}
56	}
57	}