API docs by Redocly

Globus Flows API (2024.04.02)

Download OpenAPI specification:Download

Globus Support: support@globus.org URL: https://support.globus.org/hc/en-us/requests/new Terms of Service

This is the Globus Flows API description.

Flows

Deploy a Flow

Deploy a Flow and its schema.

Authorizations:
None
Request Body schema: application/json
required
object (FlowDefinition)
title
string [ 1 .. 128 ] characters

A non-unique, human-friendly name used for displaying the provider to end users.

subtitle
string [ 1 .. 128 ] characters

A concise summary of the provider’s purpose.

description
string [ 1 .. 4096 ] characters

A detailed description of the provider for end user display.

keywords
Array of strings

A set of terms used to categorize the provider which may be used in query and discovery operations. Maximum total length of all keywords is 1024 characters.

flow_viewers
Array of strings (PrincipalURN_or_public) unique

A set of Principal URN values, or the value "public" indicating the identity of users who can view the provider description via introspection or when indexed in any provider catalog service.

flow_starters
Array of strings (PrincipalURN_or_all_authenticated_users) unique

A set of Principal URN values, or the value "all_authenticated_users" indicating the identity of users who can use the /run operation to initiate an action on the provider.

flow_administrators
Array of strings (PrincipalURN) unique

The set of Principal URN values of users who may perform administrative operations, including updating the description itself, on the provider.

input_schema
object

A published JSON Schema which input to the Flow must conform to.

subscription_id
string <uuid>

A subscription to associate with this flow.

If no subscription is specified, the flow may be created but may have limits on how long or how much it can be used.

Responses

Request samples

Content type
application/json
{
  • "definition": {
    },
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "keywords": [
    ],
  • "flow_viewers": [
    ],
  • "flow_starters": [
    ],
  • "flow_administrators": [
    ],
  • "input_schema": { },
  • "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "definition": {
    },
  • "input_schema": { },
  • "globus_auth_scope": "http://example.com",
  • "globus_auth_scopes_by_RunAs": [],
  • "user_role": "flow_viewer",
  • "flow_viewers": [
    ],
  • "flow_starters": [
    ],
  • "flow_administrators": [
    ],
  • "flow_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "synchronous": true,
  • "log_supported": true,
  • "types": [
    ],
  • "api_version": "1.0",
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "keywords": [
    ],
  • "principal_urn": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "globus_auth_username": "string",
  • "flow_url": "http://example.com",
  • "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627"
}

Retrieve all Flows

Query the Flows service for a listing of Flows available to a user according to the permissions (role) they have on the Flow.

Authorizations:
None
query Parameters
marker
string

An opaque token used to iterate through pages of returned Flows. If provided, all other query arguments will be ignored. The marker encodes all state in a given query, therefore it's unnecessary to provide query arguments once an initial marker has been received.

per_page
integer [ 1 .. 50 ]
Default: 20
Example: per_page=50

The number of results to return in a single paged response.

page
integer >= 1
Default: 1
Example: page=2

The page of results to return.

filter_roles
Array of strings
Deprecated
Default: "flow_owner,flow_viewers,flow_starters,flow_administrators"
Items Enum: "flow_owner" "flow_viewers" "flow_starters" "flow_administrators"
Example: filter_roles=flow_owner,flow_viewers

Return Flows for which the user has the supplied role. The role the user has on the Flow dictates the operations they can perform. If multiple roles are specified, the user will have at least one of the specified roles on each Flow returned.

filter_role
string
Enum: "flow_viewer" "flow_starter" "flow_administrator" "flow_owner"
Example: filter_role=flow_starter

Return Flows for which the user has the provided role. The role the user has on the Flow dictates the operations they can perform. Roles are cumulative in the sense that having, for example, the "flow_starter" role also implies having the "flow_viewer" role. Thus, specifying "flow_starter" will also include all Flows for which the user has "flow_viewer" role as well. If not provided, only Flows for which the caller has "flow_owner" role will be returned.

filter_scope_string
Array of strings
Example: filter_scope_string=0abc,100

Performs a case insensitive substring based search on the Flows' scope string fields. If multiple values are specified, each Flow returned is guaranteed to contain at least one of the strings in its scope strings.

filter_title
Array of strings
Example: filter_title=hello,science

Performs a case insensitive substring based search on the Flows' title field. If multiple values are specified, each Flow returned is guaranteed to contain at least one of the strings in its title.

filter_subtitle
Array of strings
Example: filter_subtitle=hello,science

Performs a case insensitive substring based search on the Flows' subtitle field. If multiple values are specified, each Flow returned is guaranteed to contain at least one of the strings in its subtitle.

filter_description
Array of strings
Example: filter_description=hello,science

Performs a case insensitive substring based search on the Flows' description field. If multiple values are specified, each Flow returned is guaranteed to contain at least one of the strings in its description.

filter_keywords
Array of strings
Example: filter_keywords=hello,science

Performs a case insensitive substring based search on the Flows' keywords field. If multiple values are specified, each Flow returned is guaranteed to contain at least one of the substrings as a keyword.

filter_fulltext
Array of strings
Example: filter_fulltext=globus

Given a one or more patterns, this filter searches against a pre-defined subset of fields for a match. If any of the fields match any of the patterns, the Flow is considered a match.

The fields that are automatically searched in are:

  • title
  • subtitle
  • flow_owner
  • description
  • id
  • flow_administrators
orderby
Array of strings
Example: orderby=title ASC,id DESC

An ordering criteria to apply to the resulting Flows listing. The first value indicates the field to order on, and the second value indicates the sorting order. The first ordering criteria will be used to sort the data, subsequent ordering criteria will be applied for ties.

Fields that support ordering are:

  • id
  • scope_string
  • flow_owner
  • flow_administrators
  • title
  • created_at
  • updated_at

Supported orderings are:

  • ASC
  • DESC

Responses

Response samples

Content type
application/json
{
  • "flows": [
    ],
  • "limit": 0,
  • "marker": "string",
  • "has_next_page": true
}

Validate a flow

Validate a flow definition and its schema.

Authorizations:
None
Request Body schema: application/json
required
object (FlowDefinition)
input_schema
object

A JSON Schema describing valid input to the flow.

Responses

Request samples

Content type
application/json
{
  • "definition": {
    },
  • "input_schema": { }
}

Response samples

Content type
application/json
{
  • "scopes": {
    }
}

Retrieve a Flow

Get a previously deployed Flow.

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow whose definition is being looked up.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "definition": {
    },
  • "input_schema": { },
  • "globus_auth_scope": "http://example.com",
  • "globus_auth_scopes_by_RunAs": [],
  • "user_role": "flow_viewer",
  • "flow_viewers": [
    ],
  • "flow_starters": [
    ],
  • "flow_administrators": [
    ],
  • "flow_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "synchronous": true,
  • "log_supported": true,
  • "types": [
    ],
  • "api_version": "1.0",
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "keywords": [
    ],
  • "principal_urn": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "globus_auth_username": "string",
  • "flow_url": "http://example.com",
  • "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627"
}

Update a Flow

Update a previously deployed Flow.

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow whose definition is being looked up.

Request Body schema: application/json
object (FlowDefinition)
input_schema
object

A JSON schema document.

When starting the flow, input keys and values must conform to the schema. The Globus Web App uses the input schema to created a guided input page when starting the flow.

title
string [ 1 .. 128 ] characters

A non-unique, human-friendly name used for displaying the flow to end users.

subtitle
string <= 128 characters

A short summary of the flow's purpose or functionality.

description
string <= 4096 characters

Arbitrary text to describe the Flow.

flow_owner
string

If provided, the value must be the calling user's Globus Auth identity URN, and the user must be a flow administrator.

It is not possible for non-administrators to take ownership of a flow. Also, it is currently not possible to assign ownership to another user.

flow_administrators
Array of str

A list of Globus Auth identity and group URNs that may administer the flow.

Flow administrators are able to see the full flow definition, including any parameters listed in a "__Private_Parameters" value.

flow_starters
Array of str

A list of Globus Auth identity and group URNs that may start the flow.

It is possible to make a flow available for use to all authenticated users -- including those outside your organization or domain -- by using the special value "all_authenticated_users".

Parameters listed in "__Private_Parameters" values in the definition will be removed from the definition when it is viewed by a flow starter.

flow_viewers
Array of str

A list of Globus Auth identity and group URNs that may see the flow, including its definition and input schema.

It is possible to make a flow available for viewing to all users -- including those outside your organization or domain -- by using the special value "public".

Parameters listed in "__Private_Parameters" values in the definition will be removed from the definition when it is viewed by a flow starter.

keywords
Array of str

A list of keywords that can be used for grouping or identifying flows.

string or string

Responses

Request samples

Content type
application/json
{
  • "definition": {
    },
  • "input_schema": { },
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "flow_owner": "string",
  • "flow_administrators": [
    ],
  • "flow_starters": [
    ],
  • "flow_viewers": [
    ],
  • "keywords": [
    ],
  • "subscription_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "definition": {
    },
  • "input_schema": { },
  • "globus_auth_scope": "http://example.com",
  • "globus_auth_scopes_by_RunAs": [],
  • "user_role": "flow_viewer",
  • "flow_viewers": [
    ],
  • "flow_starters": [
    ],
  • "flow_administrators": [
    ],
  • "flow_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "synchronous": true,
  • "log_supported": true,
  • "types": [
    ],
  • "api_version": "1.0",
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "keywords": [
    ],
  • "principal_urn": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "globus_auth_username": "string",
  • "flow_url": "http://example.com",
  • "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627"
}

Remove a Flow

Remove a Flow from the Flow service.

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow whose definition is being looked up.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "definition": {
    },
  • "input_schema": { },
  • "globus_auth_scope": "http://example.com",
  • "globus_auth_scopes_by_RunAs": [],
  • "user_role": "flow_viewer",
  • "flow_viewers": [
    ],
  • "flow_starters": [
    ],
  • "flow_administrators": [
    ],
  • "flow_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "synchronous": true,
  • "log_supported": true,
  • "types": [
    ],
  • "api_version": "1.0",
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "keywords": [
    ],
  • "principal_urn": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "globus_auth_username": "string",
  • "flow_url": "http://example.com",
  • "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627"
}

Retrieve all Flows Deprecated

Query the Flows service for a listing of Flows available to a user according to the permissions (role) they have on the Flow.

Authorizations:
None
query Parameters
roles
Array of strings
Default: "flow_owner"
Items Enum: "flow_owner" "flow_viewers" "flow_starters" "flow_administrators"
Example: roles=flow_owner,flow_viewers

Return Flow's for which the user has the supplied role. The role the user has on the Flow dictates the operations they can perform.

Responses

Response samples

Content type
application/json
{
  • "flows": [
    ],
  • "limit": 0,
  • "marker": "string",
  • "has_next_page": true
}

Runs

Invoke a Flow

Run an instance of a particular Flow.

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow to run.

Request Body schema: application/json
body
required
object

A Flow specific input body. If the Flow defines an input schema, this input will be validated against it. If the Flow does not define an input schema, the Flow will be run with whatever the contents of this field is.

tags
Array of strings (Tags) unique [ items [ 1 .. 256 ] characters ]

A list of tags to associate with the Run.

Tags are normalized by stripping leading and trailing whitespace, and replacing all whitespace with a single space.

Responses

Request samples

Content type
application/json
{
  • "body": { },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "action_id": "string",
  • "run_id": "string",
  • "flow_id": "string",
  • "flow_last_updated": "2019-08-24T14:15:22Z",
  • "start_time": "2019-08-24T14:15:22Z",
  • "completion_time": "2019-08-24T14:15:22Z",
  • "label": "string",
  • "status": "SUCCEEDED",
  • "display_status": "string",
  • "details": { },
  • "run_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "run_monitors": [
    ],
  • "run_managers": [
    ],
  • "user_role": "run_monitor",
  • "tags": [
    ]
}

Invoke a Flow Deprecated

Run an instance of a particular Flow.

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow to run.

Request Body schema: application/json
body
required
object

A Flow specific input body. If the Flow defines an input schema, this input will be validated against it. If the Flow does not define an input schema, the Flow will be run with whatever the contents of this field is.

tags
Array of strings (Tags) unique [ items [ 1 .. 256 ] characters ]

A list of tags to associate with the run.

Tags are normalized by stripping leading and trailing whitespace, and replacing all whitespace with a single space.

Responses

Request samples

Content type
application/json
{
  • "body": { },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "action_id": "string",
  • "run_id": "string",
  • "flow_id": "string",
  • "flow_last_updated": "2019-08-24T14:15:22Z",
  • "start_time": "2019-08-24T14:15:22Z",
  • "completion_time": "2019-08-24T14:15:22Z",
  • "label": "string",
  • "status": "SUCCEEDED",
  • "display_status": "string",
  • "details": { },
  • "run_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "run_monitors": [
    ],
  • "run_managers": [
    ],
  • "user_role": "run_monitor",
  • "tags": [
    ]
}

Remove a Run

Remove the state for a particular invocation of a Flow.

Authorizations:
None
path Parameters
run_id
required
string

The ID for the Run whose data is being released.

Responses

Response samples

Content type
application/json
{
  • "action_id": "string",
  • "run_id": "string",
  • "flow_id": "string",
  • "flow_last_updated": "2019-08-24T14:15:22Z",
  • "start_time": "2019-08-24T14:15:22Z",
  • "completion_time": "2019-08-24T14:15:22Z",
  • "label": "string",
  • "status": "SUCCEEDED",
  • "display_status": "string",
  • "details": { },
  • "run_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "run_monitors": [
    ],
  • "run_managers": [
    ],
  • "user_role": "run_monitor",
  • "tags": [
    ]
}

Resume a Run

Attempt to resume a Run, particularly when it has reached a status of INACTIVE. A Flow Run may reach an INACTIVE status when an Action type state within the Flow returns its status as INACTIVE. The resume operation on the Flow Run provides a hint that the cause of the Action becoming INACTIVE may have been cleared, and thus the resume operation on the Action Provider should be invoked to allow the Action state to resume and thus resume the Flow Run.

In the particular case that an Action state is INACTIVE with a code value of "ConsentRequired" it is further assumed that the Bearer token provided in the Authorization header on the resume operation now carries sufficient consents to continue the INACTIVE Action. Thus, the Flow service will use the Bearer token to generate new dependent tokens for running the Action and use these tokens to request that the Action be resumed at the Action Provider.

Note again that in reasons other than "ConsentRequired" for a Flow or Action to go INACTIVE, the resume operation is just a hint. For example, when the code is "ActivationRequired," indicating that a Globus collection or endpoint needs to be Activated by the user, performing that Activation out-of-band from the Flow will allow the Flow to proceed even without the resume operation as the Action is periodically polled for progress. Performing the resume operation may simply cause a poll to happen more quickly and thus allow the Action to resume more quickly.

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow which launched the Run.

run_id
required
string

The ID for the Run whose data is being resumed.

Responses

Response samples

Content type
application/json
{
  • "action_id": "string",
  • "run_id": "string",
  • "flow_id": "string",
  • "flow_last_updated": "2019-08-24T14:15:22Z",
  • "start_time": "2019-08-24T14:15:22Z",
  • "completion_time": "2019-08-24T14:15:22Z",
  • "label": "string",
  • "status": "SUCCEEDED",
  • "display_status": "string",
  • "details": { },
  • "run_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "run_monitors": [
    ],
  • "run_managers": [
    ],
  • "user_role": "run_monitor",
  • "tags": [
    ]
}

Cancel a Run

Cancel the execution for a particular Run of a Flow.

Authorizations:
None
path Parameters
run_id
required
string

The ID for the Run to cancel.

Responses

Response samples

Content type
application/json
{
  • "action_id": "string",
  • "run_id": "string",
  • "flow_id": "string",
  • "flow_last_updated": "2019-08-24T14:15:22Z",
  • "start_time": "2019-08-24T14:15:22Z",
  • "completion_time": "2019-08-24T14:15:22Z",
  • "label": "string",
  • "status": "SUCCEEDED",
  • "display_status": "string",
  • "details": { },
  • "run_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "run_monitors": [
    ],
  • "run_managers": [
    ],
  • "user_role": "run_monitor",
  • "tags": [
    ]
}

Get execution details on a Run

Retrieve detailed execution information for a particular Flow Run

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow which launched the Run.

run_id
required
string

The ID for the Run whose log is getting pulled.

query Parameters
limit
integer
Default: 10

An integer limit on the number of log records returned.

reverse_order
boolean
Default: false

A flag to indicate if log records should be returned in reverse order.

pagination_token
string

A token used to iterate through pages of returned log records.

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "marker": "string",
  • "has_next_page": true,
  • "entries": [
    ]
}

Get execution details on a Run

Retrieve detailed execution information for a particular Flow Run

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow which launched the Run.

run_id
required
string

The ID for the Run whose log is getting pulled.

query Parameters
limit
integer
Default: 10

An integer limit on the number of log records returned.

reverse_order
boolean
Default: false

A flag to indicate if log records should be returned in reverse order.

pagination_token
string

A token used to iterate through pages of returned log records.

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "marker": "string",
  • "has_next_page": true,
  • "entries": [
    ]
}

Get execution details on a Run

Retrieve detailed execution information for a particular Flow Run

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow which launched the Run.

run_id
required
string

The ID for the Run whose log is getting pulled.

query Parameters
limit
integer
Default: 10

An integer limit on the number of log records returned.

reverse_order
boolean
Default: false

A flag to indicate if log records should be returned in reverse order.

pagination_token
string

A token used to iterate through pages of returned log records.

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "marker": "string",
  • "has_next_page": true,
  • "entries": [
    ]
}

Get execution details on a Run

Retrieve detailed execution information for a particular Flow Run

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow which launched the Run.

run_id
required
string

The ID for the Run whose log is getting pulled.

query Parameters
limit
integer
Default: 10

An integer limit on the number of log records returned.

reverse_order
boolean
Default: false

A flag to indicate if log records should be returned in reverse order.

pagination_token
string

A token used to iterate through pages of returned log records.

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "marker": "string",
  • "has_next_page": true,
  • "entries": [
    ]
}

Get a Flow's Runs

Retrieve a listing of Runs launched from a particular Flow. If hitting the */actions endpoint, the response will list the Runs under a "actions" key. If hitting the */runs endpoint, the response will list the Runs under a "runs" key.

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow which launched the Runs.

query Parameters
marker
string

An opaque token used to iterate through pages of returned Actions. If provided, all other query arguments will be ignored. The marker encodes all state in a given query, therefore it's unnecessary to provide query arguments once an initial marker has been received.

pagination_token
string
Deprecated

("marker" is now the preferred name for this parameter.) An opaque token used to iterate through pages of returned Actions. If provided, all other query arguments will be ignored. The pagination_token encodes all state in a given query, therefore it's unnecessary to provide query arguments once an initial token has been received.

per_page
integer [ 1 .. 50 ]
Default: 20
Example: per_page=50

The number of results to return in a single paged response.

page
integer >= 1
Default: 1
Example: page=2

The page of results to return.

filter_roles
Array of strings
Deprecated
Default: "run_owner"
Items Enum: "run_owner" "run_manager" "run_monitor"
Example: filter_roles=run_manager

Return Actions for which the user has the supplied role. The role the user has on the Action dictates the operations they can perform. If multiple roles are specified, the user will have at least one of the specified roles on each Action returned.

filter_role
string
Enum: "run_monitor" "run_manager" "run_owner"
Example: filter_role=run_manager

Return Actions for which the user has the provided role. The role the user has on the Action dictates the operations they can perform. Roles are cumulative in the sense that having, for example, the "run_manager" role also implies having the "run_monitor" role. Thus, specifying manager will also include all Actions for which the user has "run_monitor" role as well. If not provided, only Actions for which the caller has "run_owner" role will be returned.

filter_status
Array of strings
Items Enum: "SUCCEEDED" "FAILED" "ENDED" "ACTIVE" "INACTIVE"
Example: filter_status=FAILED,INACTIVE

Return Actions which are in the specified state. The state of the Action dictates the operations which can performed on them. If multiple statuses are specified, each Action returned will be in one of the specified states. By default, Actions in any state will be returned.

filter_label
Array of strings
Example: filter_label=science,tests

Performs a case insensitive string based search on the Actions' label fields. If multiple values are specified, each Action returned is guaranteed to contain at least one of the strings in its label.

filter_completion_time
any
Example: filter_completion_time=2021-03-09T21:52:14,2021-03-09T21:53

Given a pair of comma separated ISO 8601 date/time strings, filter results to only those Actions whose completion time is within the specified range. If one of the dates is omitted, it forms an open range, so "dt," returns all records with date greater or equal to dt, and ",dt" returns all records with dates less than dt. If there is no comma, it is treated in the same way as "dt,". Results will contain Actions which completed between the first date/time string onwards, up to (but not including) the second date/time string. Note that Actions which are still running will have null completion times and thus cannot be filtered by this field.

filter_start_time
any
Example: filter_start_time=2021-03-09T21:52:14,2021-03-09T21:53

Given a pair of comma separated ISO 8601 date/time strings, filter results to only those Actions which started running within the specified range. If one of the dates is omitted, it forms an open range, so "dt," returns all records with date greater or equal to dt, and ",dt" returns all records with dates less than dt. If there is no comma, it is treated in the same way as "dt,". Results will contain Actions which began between the first date/time string onwards, up to (but not including) the second date/time string.

orderby
Array of strings
Example: orderby=start_time ASC,id DESC

An ordering criteria to apply to the resulting Action listing. The first value indicates the field to order on, and the second value indicates the sorting order. The first ordering criteria will be used to sort the data, subsequent ordering criteria will be applied for ties.

Fields that support ordering are:

  • id
  • start_time
  • completion_time
  • status
  • label

Supported orderings are:

  • ASC
  • DESC

Responses

Response samples

Content type
application/json
{
  • "marker": "string",
  • "has_next_page": true,
  • "actions": [
    ]
}

Get a Flow's Runs

Retrieve a listing of Runs launched from a particular Flow. If hitting the */actions endpoint, the response will list the Runs under a "actions" key. If hitting the */runs endpoint, the response will list the Runs under a "runs" key.

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow which launched the Runs.

query Parameters
marker
string

An opaque token used to iterate through pages of returned Actions. If provided, all other query arguments will be ignored. The marker encodes all state in a given query, therefore it's unnecessary to provide query arguments once an initial marker has been received.

pagination_token
string
Deprecated

("marker" is now the preferred name for this parameter.) An opaque token used to iterate through pages of returned Actions. If provided, all other query arguments will be ignored. The pagination_token encodes all state in a given query, therefore it's unnecessary to provide query arguments once an initial token has been received.

per_page
integer [ 1 .. 50 ]
Default: 20
Example: per_page=50

The number of results to return in a single paged response.

page
integer >= 1
Default: 1
Example: page=2

The page of results to return.

filter_roles
Array of strings
Deprecated
Default: "run_owner"
Items Enum: "run_owner" "run_manager" "run_monitor"
Example: filter_roles=run_manager

Return Actions for which the user has the supplied role. The role the user has on the Action dictates the operations they can perform. If multiple roles are specified, the user will have at least one of the specified roles on each Action returned.

filter_role
string
Enum: "run_monitor" "run_manager" "run_owner"
Example: filter_role=run_manager

Return Actions for which the user has the provided role. The role the user has on the Action dictates the operations they can perform. Roles are cumulative in the sense that having, for example, the "run_manager" role also implies having the "run_monitor" role. Thus, specifying manager will also include all Actions for which the user has "run_monitor" role as well. If not provided, only Actions for which the caller has "run_owner" role will be returned.

filter_status
Array of strings
Items Enum: "SUCCEEDED" "FAILED" "ENDED" "ACTIVE" "INACTIVE"
Example: filter_status=FAILED,INACTIVE

Return Actions which are in the specified state. The state of the Action dictates the operations which can performed on them. If multiple statuses are specified, each Action returned will be in one of the specified states. By default, Actions in any state will be returned.

filter_label
Array of strings
Example: filter_label=science,tests

Performs a case insensitive string based search on the Actions' label fields. If multiple values are specified, each Action returned is guaranteed to contain at least one of the strings in its label.

filter_completion_time
any
Example: filter_completion_time=2021-03-09T21:52:14,2021-03-09T21:53

Given a pair of comma separated ISO 8601 date/time strings, filter results to only those Actions whose completion time is within the specified range. If one of the dates is omitted, it forms an open range, so "dt," returns all records with date greater or equal to dt, and ",dt" returns all records with dates less than dt. If there is no comma, it is treated in the same way as "dt,". Results will contain Actions which completed between the first date/time string onwards, up to (but not including) the second date/time string. Note that Actions which are still running will have null completion times and thus cannot be filtered by this field.

filter_start_time
any
Example: filter_start_time=2021-03-09T21:52:14,2021-03-09T21:53

Given a pair of comma separated ISO 8601 date/time strings, filter results to only those Actions which started running within the specified range. If one of the dates is omitted, it forms an open range, so "dt," returns all records with date greater or equal to dt, and ",dt" returns all records with dates less than dt. If there is no comma, it is treated in the same way as "dt,". Results will contain Actions which began between the first date/time string onwards, up to (but not including) the second date/time string.

orderby
Array of strings
Example: orderby=start_time ASC,id DESC

An ordering criteria to apply to the resulting Action listing. The first value indicates the field to order on, and the second value indicates the sorting order. The first ordering criteria will be used to sort the data, subsequent ordering criteria will be applied for ties.

Fields that support ordering are:

  • id
  • start_time
  • completion_time
  • status
  • label

Supported orderings are:

  • ASC
  • DESC

Responses

Response samples

Content type
application/json
{
  • "marker": "string",
  • "has_next_page": true,
  • "actions": [
    ]
}

List all Runs

Retrieve a listing of Actions/Runs launched across all Flows. If hitting the */actions endpoint, the response will list the Runs under a "actions" key. If hitting the */runs endpoint, the response will list the Runs under a "runs" key.

Authorizations:
None
query Parameters
marker
string

An opaque token used to iterate through pages of returned Actions. If provided, all other query arguments will be ignored. The marker encodes all state in a given query, therefore it's unnecessary to provide query arguments once an initial marker has been received.

pagination_token
string
Deprecated

("marker" is now the preferred name for this parameter.) An opaque token used to iterate through pages of returned Actions. If provided, all other query arguments will be ignored. The pagination_token encodes all state in a given query, therefore it's unnecessary to provide query arguments once an initial token has been received.

per_page
integer [ 1 .. 50 ]
Default: 20
Example: per_page=50

The number of results to return in a single paged response.

page
integer >= 1
Default: 1
Example: page=2

The page of results to return.

filter_roles
Array of strings
Deprecated
Default: "run_owner"
Items Enum: "run_owner" "run_managers" "run_monitors"
Example: filter_roles=run_owner,run_managers

Return Runs for which the user has the supplied role. The role the user has on the Action dictates the operations they can perform. If multiple roles are specified, the user will have at least one of the specified roles on each Action returned.

filter_role
string
Enum: "run_monitor" "run_manager" "run_owner"
Example: filter_role=run_manager

Return Runs for which the user has the provided role. The role the user has on the Runs dictates the operations they can perform. Roles are cumulative in the sense that having, for example, the "run_manager" role also implies having the "run_monitor" role. Thus, specifying manager will also include all Runs for which the user has "run_monitor" role as well. If not provided, only Runs for which the caller has "run_owner" role will be returned.

filter_status
Array of strings
Items Enum: "SUCCEEDED" "FAILED" "ENDED" "ACTIVE" "INACTIVE"
Example: filter_status=FAILED,INACTIVE

Return Actions which are in the specified state. The state of the Action dictates the operations which can performed on them. If multiple statuses are specified, each Action returned will be in one of the specified states. By default, Actions in any state will be returned.

filter_label
Array of strings
Example: filter_label=science,tests

Performs a case insensitive string based search on the Actions' label fields. If multiple values are specified, each Action returned is guaranteed to contain at least one of the strings in its label.

filter_flow_title
Array of strings
Example: filter_flow_title=globus,tests

Performs a case insensitive string based search to filter for Actions which have parent Flow's with a matching title(s). If multiple values are specified, each Action returned will have a parent Flow with a title matching at least one of the strings.

filter_flow_id
Array of strings <uuid>
Example: filter_flow_id=6086d817-19d9-4f5b-9329-22ed12d4d3dd,71a70751-19a5-4d19-998e-0709c40321e9

Performs an equality based search to filter for Runs which were initiated from the specified Flow ID(s). If multiple values are specified, each Run returned will have been initiated from at least one of the specified Flow IDs.

filter_completion_time
any
Example: filter_completion_time=2021-03-09T21:52:14,2021-03-09T21:53

Given a pair of comma separated ISO 8601 date/time strings, filter results to only those Actions whose completion time is within the specified range. If one of the dates is omitted, it forms an open range, so "dt," returns all records with date greater or equal to dt, and ",dt" returns all records with dates less than dt. If there is no comma, it is treated in the same way as "dt,". Results will contain Actions which completed between the first date/time string onwards, up to (but not including) the second date/time string. Note that Actions which are still running will have null completion times and thus cannot be filtered by this field.

filter_start_time
any
Example: filter_start_time=2021-03-09T21:52:14,2021-03-09T21:53

Given a pair of comma separated ISO 8601 date/time strings, filter results to only those Actions which started running within the specified range. If one of the dates is omitted, it forms an open range, so "dt," returns all records with date greater or equal to dt, and ",dt" returns all records with dates less than dt. If there is no comma, it is treated in the same way as "dt,". Results will contain Actions which began between the first date/time string onwards, up to (but not including) the second date/time string.

orderby
Array of strings
Example: orderby=start_time ASC,id DESC

An ordering criteria to apply to the resulting Action listing. The first value indicates the field to order on, and the second value indicates the sorting order. The first ordering criteria will be used to sort the data, subsequent ordering criteria will be applied for ties.

Fields that support ordering are:

  • id
  • start_time
  • completion_time
  • status
  • label
  • run_owner
  • flow_title

Supported orderings are:

  • ASC
  • DESC

Responses

Response samples

Content type
application/json
{
  • "marker": "string",
  • "has_next_page": true,
  • "actions": [
    ],
  • "runs": [
    ]
}

Get details about a run

Get details about a run.

Authorizations:
None
path Parameters
run_id
required
string

The ID for the Run.

query Parameters
include_flow_description
string
Enum: true true false false
Example: include_flow_description=true

If present and set to a true value, metadata about the associated flow will be included.

Responses

Response samples

Content type
application/json
{
  • "action_id": "string",
  • "run_id": "string",
  • "flow_id": "string",
  • "flow_last_updated": "2019-08-24T14:15:22Z",
  • "start_time": "2019-08-24T14:15:22Z",
  • "completion_time": "2019-08-24T14:15:22Z",
  • "label": "string",
  • "status": "SUCCEEDED",
  • "display_status": "string",
  • "details": { },
  • "run_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "run_monitors": [
    ],
  • "run_managers": [
    ],
  • "user_role": "run_monitor",
  • "tags": [
    ],
  • "flow_description": {
    }
}

Update a Run's metadata

Modify a Run's metadata.

By default only the Run initiator is able to modify a Run's metadata. Note that delegating manage access to a principal will allow them to further alter the principals with monitor and manage access.

Authorizations:
None
path Parameters
run_id
required
string

The ID for the Run.

Request Body schema: application/json
label
string (Label) [ 1 .. 64 ] characters

A label that helps identify the run.

run_monitors
Array of strings (Run monitors) ^urn:globus:(auth:identity|groups:id):([a-fA-...

A list of principal URNs containing identities which are allowed to monitor the progress of the Run using the status and log operations. When not provided, only the user that initiated the Run can monitor it.

run_managers
Array of strings (Run managers) ^urn:globus:(auth:identity|groups:id):([a-fA-...

A list of principal URNs containing identities which are allowed to manage a Run using the cancel and release and update operations. When not provided, only the user that initiated the Run can manage it.

tags
Array of strings (Tags) unique [ items [ 1 .. 256 ] characters ]

A list of tags to associate with the Run.

The list of tags will replace the existing list of tags associated with the run. If an empty list is submitted, all existing tags will be removed.

Tags are normalized by stripping leading and trailing whitespace, and by replacing all whitespace with a single space.

Responses

Request samples

Content type
application/json
{
  • "label": [
    ],
  • "run_monitors": [
    ],
  • "run_managers": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "action_id": "string",
  • "run_id": "string",
  • "flow_id": "string",
  • "flow_last_updated": "2019-08-24T14:15:22Z",
  • "start_time": "2019-08-24T14:15:22Z",
  • "completion_time": "2019-08-24T14:15:22Z",
  • "label": "string",
  • "status": "SUCCEEDED",
  • "display_status": "string",
  • "details": { },
  • "run_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "run_monitors": [
    ],
  • "run_managers": [
    ],
  • "user_role": "run_monitor",
  • "tags": [
    ]
}

Get the Flow definition and input schema that were used to start a Run

Flow definitions and input schemas may be updated after a Run has been started.

This route allows users to view the Flow definition and input schema that were used to start a given Run.

Authorizations:
None
path Parameters
run_id
required
string

The UUID of the Run.

Responses

Response samples

Content type
application/json
{
  • "flow_id": "string",
  • "definition": { },
  • "input_schema": { }
}

Batch

Update metadata for multiple Runs.

Request Body schema: application/json
required
object
object (BatchRunUpdateSetOperation)
object (BatchRunUpdateOperation)
object (BatchRunUpdateOperation)

Request samples

Content type
application/json
{
  • "filters": {
    },
  • "set": {
    },
  • "add": {
    },
  • "remove": {
    }
}