Task History API

Introduction

The Task History API allows you to query your users' usage of integration workflows and access data from historical workflow executions.

Task History API is available for Paragon customers on Enterprise plans. To learn more, contact your Customer Success Manager or sales@useparagon.com.

When to use the Task History API

The Task History API can be used to analyze integration usage or pull information about historical workflow executions into your application. For example, you can use the Task History API to:

Query the number of workflow executions that ran last week for the Salesforce integration
Query all failed workflow executions for a specific user
Export all tasks that occurred in a specific month into Google BigQuery

You can find example queries in the request format below.

Generating API Keys

The Task History API authorizes with a project-level API Key, instead of the Paragon User Token.

API Keys provide access to all Connected Users in the project they are created in and can be rotated or deleted after being generated.

To generate a new project-level API Key:

Visit your Project's Settings > API Keys.
Click "Create API Key". Provide a meaningful name for the API Key for your reference.
The API Key will appear on a one-time basis for you to save in a secure place.

Examples

Querying Salesforce workflow executions run during a week's time period

GET /projects/<Paragon Project ID>/task-history/workflow-executions?integration=salesforce&afterDate=2023-02-16T00:00:00&beforeDate=2023-02-23T00:00:00

Authorization: Bearer <Paragon API Key>

Response example:

{
    "workflowExecutions": [
        {
            "id": "c70cafa5-4f80-45c7-b5b3-71454f6d638d",
            "userId": "d1f142cd-1dfe-4d76-ab4c-8f64901a9c5c",
            "taskCount": 1,
            "runDuration": 1477,
            "workflowId": "c395c170-4541-499c-afd1-0eccfaae49c9",
            "status": "SUCCEEDED",
            "dateEnded": "2023-02-20T06:21:43.751Z",
            "dateStarted": "2023-02-20T06:21:42.274Z"
        },
        ...
    ],
    "nextLink": "https://zeus.useparagon.com/projects/d1f142cd-1dfe-4d76-ab4c-8f64901a9c5c/task-history/workflow-executions?integration=salesforce&afterDate=2023-02-16T00:00:00&beforeDate=2023-02-23T00:00:00&sortBy=ASC&offset=100",
    "total": 14295
}

Querying failed workflow executions for a user

GET /projects/<Paragon Project ID>/task-history/workflow-executions?userId=test@example.com&status=FAILED

Authorization: Bearer <Paragon API Key>

Response example:

{
    "workflowExecutions": [
        {
            "id": "317a396c-7dc8-4a1f-8ceb-b39d5ad845da",
            "userId": "123456",
            "taskCount": 0,
            "runDuration": 3847,
            "workflowId": "24cf377b-c7f5-40e7-9b10-6cc5d811266a",
            "status": "FAILED",
            "dateEnded": "2023-03-01T11:15:04.051Z",
            "dateStarted": "2023-03-01T11:15:00.204Z"
        },
        ...
    ],
    "nextLink": "https://zeus.useparagon.com/projects/d1f142cd-1dfe-4d76-ab4c-8f64901a9c5c/task-history/workflow-executions?userId=test@example.com&status=FAILED&sortBy=ASC&offset=100",
    "total": 180
}

Endpoint Reference

Base URL

The Base URL of the Task History API endpoints begin with the same origin as the Connect and Users APIs.

For cloud customers who sign in to dashboard.useparagon.com, the Base URL is https://api.useparagon.com/projects/<Project ID>/task-history
For on-premise customers who sign in to dashboard.<On-Premise URL>, the base URL is https://zeus.<On-Premise URL>/projects/<Project ID>/task-history

Authorization

Requests to the Task History API must provide an API Key as a Bearer-type Authorization header in the request:

GET /projects/<Paragon Project ID>/task-history/workflow-executions

Authorization: Bearer <Paragon API Key>

Pagination

API responses that include multiple objects will be provided in page size of 100. In the case that there are additional pages of data available, the API response will include a URL to get the next 100 records.

Rate Limits

The Task History API has a rate limit of 1,000 requests per 10 minutes. If you need higher rate limits, please reach out to our team at support@useparagon.com

API Methods

Get workflow executions

GET [Base URL]/workflow-executions

Search through historical workflow executions with the below filtering options as query parameters.

Query Parameters

Name Type Description

Name	Type	Description
userId	String	Filter executions by a specific Connected User ID.
workflowId	UUID	Filter executions for a specific workflow ID.
integration	String	Filter executions for a specific integration, for example, `salesforce`. The integration name is in the same format as provided to `paragon.connect`.
status	String	Filter executions by a status: `EXECUTING` \| `FAILED` \| `SUCCEEDED` \| `DELAYED`
beforeDate	String (Date)	Filter executions that began before a certain timestamp, in ISO 8601 format (for example, `2023-02-22`)
afterDate	String (Date)	Filter executions that began after a certain timestamp, in ISO 8601 format
offset	Number	Offset results by a fixed number of records.
sortBy	String	Sort by execution time: `ASC` \| `DESC`. Defaults to `DESC`.

userId

String

Filter executions by a specific Connected User ID.

workflowId

UUID

Filter executions for a specific workflow ID.

integration

String

Filter executions for a specific integration, for example, salesforce. The integration name is in the same format as provided to paragon.connect.

status

String

Filter executions by a status:

EXECUTING | FAILED | SUCCEEDED | DELAYED

beforeDate

String (Date)

Filter executions that began before a certain timestamp, in ISO 8601 format (for example, 2023-02-22)

afterDate

String (Date)

Filter executions that began after a certain timestamp, in ISO 8601 format

offset

Number

Offset results by a fixed number of records.

sortBy

String

Sort by execution time: ASC | DESC. Defaults to DESC.

{
    "workflowExecutions": [
        {
            "id": "c70cafa5-4f80-45c7-b5b3-71454f6d638d",
            "userId": "d1f142cd-1dfe-4d76-ab4c-8f64901a9c5c",
            "taskCount": 1,
            "runDuration": 1477,
            "workflowId": "c395c170-4541-499c-afd1-0eccfaae49c9",
            "status": "SUCCEEDED",
            "dateEnded": "2023-02-20T06:21:43.751Z",
            "dateStarted": "2023-02-20T06:21:42.274Z"
        },
        // ...
    ],
    // nextLink is `null` if there are no more results
    "nextLink": "https://zeus.useparagon.com/projects/d1f142cd-1dfe-4d76-ab4c-8f64901a9c5c/task-history/workflow-executions?integration=salesforce&afterDate=2023-02-16T00:00:00&beforeDate=2023-02-23T00:00:00&sortBy=ASC&offset=100",
    "total": 14295
}

Get workflow execution by ID

GET [Base URL]/workflow-executions/:executionID

Get details for a specific workflow execution by its Execution ID.

Path Parameters

Name	Type	Description
executionID*	UUID	The ID of the execution to get details for.

Name

Type

Description

executionID*

UUID

The ID of the execution to get details for.

Query Parameters

Name	Type	Description
userId	String	Yzv91QRt70Bw
workflowId	UUID	a7Ic0zXfjUrC
integration	String	RNuGcsiqDxH4
status	String	PnuwoED6G944
beforeDate	String (Date)	fpnUW6vLSCxd
afterDate	String (Date)	5KROzmJI2Xsp
offset	Number	PGoEMljYVuwF
sortBy	String	GwurNRgm5Lzg

Name

Type

Description

userId

String

Yzv91QRt70Bw

workflowId

UUID

a7Ic0zXfjUrC

integration

String

RNuGcsiqDxH4

status

String

PnuwoED6G944

beforeDate

String (Date)

fpnUW6vLSCxd

afterDate

String (Date)

5KROzmJI2Xsp

offset

Number

PGoEMljYVuwF

sortBy

String

GwurNRgm5Lzg

{
    "id": "daff08e3-c299-4005-9799-be69090ebae1",
    "userId": "test",
    "taskCount": 1,
    "runDuration": 8,
    "workflowId": "88d20d69-e585-4eea-aac4-5b7aea0521e8",
    "status": "FAILED",
    "dateEnded": "2022-11-25T22:15:07.987Z",
    "dateStarted": "2022-11-25T22:15:00.038Z",
    "stepExecutions": [
        {
            "id": "5fec7d78-7e10-4b4a-bdfc-292f629774bf",
            "stepId": "0f7cce44-d292-4555-bae8-5b904a0c4ac9",
            "workflowExecutionId": "daff08e3-c299-4005-9799-be69090ebae1",
            "status": "SUCCEEDED",
            "type": "TRIGGER/CRON",
            "start": "2022-11-25T22:15:00.075Z",
            "end": "2022-11-25T22:15:00.084Z",
            "next": [
                "29e675eb-0910-4d5c-8a5c-a4a4c1895605"
            ],
            "prev": null,
            "inputSize": "220",
            "outputSize": "76"
        },
        {
            "id": "29e675eb-0910-4d5c-8a5c-a4a4c1895605",
            "stepId": "7459bbf5-e55b-49e8-9390-084cf86752e5",
            "workflowExecutionId": "daff08e3-c299-4005-9799-be69090ebae1",
            "status": "FAILED",
            "type": "ACTION/REQUEST",
            "start": "2022-11-25T22:15:07.850Z",
            "end": "2022-11-25T22:15:07.873Z",
            "next": [],
            "prev": "5fec7d78-7e10-4b4a-bdfc-292f629774bf",
            "inputSize": "712",
            "outputSize": "824"
        }
    ]
}

Get details for step of workflow execution

GET [Base URL]/workflow-executions/:executionID/step-executions/:stepExecutionID

Get details for a specific step of a workflow execution, by its Execution ID and Step Execution ID. These details include step input/output and run duration for the specific step.

Path Parameters

Name	Type	Description
executionID*	UUID	The ID of the execution to get details for.
stepExecutionID*	UUID	The ID of the step execution to get details for

Name

Type

Description

executionID*

UUID

The ID of the execution to get details for.

stepExecutionID*

UUID

The ID of the step execution to get details for

{
    "isLargeInput": false,
    "isLargeOutput": false,
    "input": {},
    "output": "Error: no auth mechanism defined"
}

POST [Base URL]/workflow-executions/:executionID/replay

Path Parameters

Name	Type	Description
executionID*	UUID	fvXUrApFKfUw
stepExecutionID*	UUID	XZUB5WdE5iHr

Name

Type

Description

executionID*

UUID

fvXUrApFKfUw

stepExecutionID*

UUID

XZUB5WdE5iHr

POST [Base URL]/workflow-executions/:executionID/replay

Replay a specific workflow execution, using the same version of the workflow that the execution originally ran with.

This endpoint is in beta and may not be suitable for use in your production application. Please send any feedback you have about this endpoint to support@useparagon.com!

PreviousUsers API NextSDK / API Reference

Last updated 3 days ago