Scripts

Endpoints for managing scripts, script runs, script sources, script permissions, and dependency management. Use these endpoints to create and manage scripts, execute scripts, manage source files, and generate dependency bundles.

Action

When the action was performed, and details about the user who did it

Properties

Name	Type	Description	Restrictions
dateTime	string(date-time)	When the action was performed	read-only
user	User¦null	A user referenced by their unique identifier

Example

{
  "dateTime": "2019-10-30T15:03:27Z",
  "user": {
    "id": "V0ZVc2VyHzU1MDg3OTc0MDE4MDg4OTY"
  }
}

AsyncAcceptedResponse

Response body for asynchronous operations. Contains an operationLocation field that specifies the URL to poll for the operation result. This URL can also be found in the Location header on the response.

Properties

Name	Type	Description	Restrictions
operationLocation	string	The URL to poll for the operation result.

Example

{
  "operationLocation": "https://api.app.wdesk.com/operations/128f274395254cf17eda6b3eb3d021b9"
}

DependencyState

Whether the run executed against an up-to-date dependency bundle, captured at run time.

Properties

Name	Type	Description	Restrictions
requirementsInSync	boolean	Whether the run used a dependencies.zip generated from the requirements.txt that was current when the run started.	read-only
runtimeInSync	boolean	Whether the dependencies.zip the run consumed was built for the same runtime as the run.	read-only

Example

{
  "requirementsInSync": true,
  "runtimeInSync": true
}

DownloadUrl

Contains a presigned URL that can be used to download content.

Properties

Name	Type	Description	Restrictions
downloadUrl	string	The URL to make a GET request to, to download the content. This is a temporary URL; it should be used immediately when the response is received.	required

Example

{
  "downloadUrl": "string"
}

ErrorDetails

Additional details of the error

Properties

Name	Type	Description	Restrictions
code	string	One of a server-defined set of error codes.
message	string	A human-readable representation of the error.
target	string	The target of the error.

Example

{
  "code": "InvalidOrder",
  "message": "Ordering by 'name desc' is not supported",
  "target": "name"
}

ErrorResponse

Error response that indicates that the service is not able to process the incoming request. The reason is provided in the error message.

Properties

Name	Type	Description	Restrictions
code	string	One of a server-defined set of error codes.
details	[ErrorDetails]	A list of additional, more specific details about the error.
documentationUrl	string	Link to some documentation relevant to the issue or endpoint in use.
message	string	A human-readable representation of the error.
target	string	The target of the error.
version	string	The API version in use when the error occurred.

Example

{
  "code": "BadArgument",
  "details": [
    {
      "code": "InvalidOrder",
      "message": "Ordering by 'name desc' is not supported",
      "target": "name"
    }
  ],
  "documentationUrl": "https://developers.workiva.com",
  "message": "The provided $orderBy option is not supported.",
  "target": "$orderBy",
  "version": "2026-01-01"
}

JSONPatchDocument

Represents a collection of JSON patch operations. For more information, refer to the PATCH Update documentation.

Properties

Name	Type	Description	Restrictions
anonymous	[JSONPatchOperation]	Represents a collection of JSON patch operations. For more information, refer to the PATCH Update documentation.

Example

[
  {
    "op": "replace",
    "path": "/name",
    "value": "New name"
  }
]

JSONPatchOperation

Represents a single JSON Patch operation. For more information, refer to the PATCH Update documentation.

Properties

Name	Type	Description	Restrictions
from	string	A JSON Pointer to the location to copy or move a value from. Required for the move and copy operations.
op	string	The operation to perform.	required
path	string	A JSON Pointer to the target location within the document.	required
value	any	The value to apply. Required for the add, replace, and test operations.

Enumerated Values

Property	Value
op	add
op	remove
op	replace
op	move
op	copy
op	test

Example

{
  "op": "replace",
  "path": "/name",
  "value": "New name"
}

ResourceLimits

Resource limits for script execution.

Properties

Name	Type	Description	Restrictions
allocatedTimeSeconds	integer(int64)	The maximum run time, in seconds, before Scripting attempts termination.	read-only
cpuCores	number(double)	The CPU available to a run, in cores. Absent on runs that started before the CPU limit was recorded.	read-only
diskBytes	integer(int64)	The maximum temporary disk usage available to a run, in bytes.	read-only
memoryBytes	integer(int64)	The maximum memory available to a run, in bytes.	read-only
terminationGracePeriodSeconds	integer(int64)	The time, in seconds, a run is given to exit after SIGTERM before SIGKILL is sent.	read-only

Example

{
  "allocatedTimeSeconds": 14400,
  "cpuCores": 1,
  "diskBytes": 2147483648,
  "memoryBytes": 1073741824,
  "terminationGracePeriodSeconds": 15
}

ResourcePermission

Mapping of the permission applied to a resource and the details of the principal to which the permission is assigned.

Properties

Name	Type	Description	Restrictions
permission	string	The unique identifier of the permission	required
principal	string	The unique identifier of the principal	required
principalType	string	The type of the principal. Refer to the principalType field to see possible types.	read-only
resource	string	The unique identifier of the resource	read-only

Enumerated Values

Property	Value
principalType	user
principalType	group

Example

{
  "permission": "ae82b647-8e43-44c3-a4e7-2aa3294c87ac",
  "principal": "V0ZVc2VyHzU2NDg2NjU2MjQ0NDQ5Mjg",
  "principalType": "user",
  "resource": "ae82b647-8e43-44c3-a4e7-2aa3294c87ac"
}

ResourcePermissionsListResult

Returns a JSON object with data and @nextLink properties. data contains a list of ResourcePermission objects, and @nextLink provides the URL to the next set of results. If there are no additional results, @nextLink doesn’t appear. If the request returns no results at all, data contains an empty array.

Properties

Name	Type	Description	Restrictions
@nextLink	string¦null	Pagination link for next set of results
data	[ResourcePermission]	The list of ResourcePermission objects returned by the request.	required

Example

{
  "@nextLink": "<opaque_url>",
  "data": [
    {
      "permission": "85aa87ee-beb9-4417-8fa0-420e9de63534",
      "principal": "V0ZVc2VyHzU2NDg2NjU2MjQ0NDQ5Mjg",
      "principalType": "user",
      "resource": "014b90fd-0631-422c-b94e-1240c53f1d6d"
    },
    {
      "permission": "85aa87ee-beb9-4417-8fa0-420e9de63534",
      "principal": "V0ZVc2VyHzUQ0NDQ5Mjg2NDg2NjU2Mj",
      "principalType": "group",
      "resource": "014b90fd-b94e-0631-422c-1240c53f1d6d"
    }
  ]
}

ResourcePermissionsModification

Details about the permissions modification

Properties

Name	Type	Description	Restrictions
toAssign	[ResourcePermission]¦null	The list of permissions to be assigned to the resource
toRevoke	[ResourcePermission]¦null	The list of permissions to be revoked from the resource

Example

{
  "toAssign": [
    {
      "permission": "598e8fa3-3e7c-4fb7-b662-f44522216e2b",
      "principal": "V0ZVc2VyHzU2NDg2NjU2MjQ0NDQ5Mjg"
    }
  ],
  "toRevoke": [
    {
      "permission": "85aa87ee-beb9-4417-8fa0-420e9de63534",
      "principal": "V0ZVc2VyHzU2NDg2NjU2MjQ0NDQ5Mjg"
    }
  ]
}

ResourceUsage

Observed resource usage during a script run.

Properties

Name	Type	Description	Restrictions
cpuPercentAverage	number(float)	Average CPU usage as a percentage.	read-only
cpuPercentPeak	number(float)	Peak CPU usage as a percentage.	read-only
dataStatus	string	Whether usage data is available, not sampled, or partial.	read-only
diskBytesAverage	integer(int64)	Average temporary disk usage in bytes.	read-only
diskBytesPeak	integer(int64)	Peak temporary disk usage in bytes.	read-only
memoryBytesAverage	integer(int64)	Average memory usage in bytes.	read-only
memoryBytesPeak	integer(int64)	Peak memory usage in bytes.	read-only
sampleCount	integer	The number of resource samples recorded.	read-only

Enumerated Values

Property	Value
dataStatus	available
dataStatus	not_sampled
dataStatus	partial

Example

{
  "cpuPercentAverage": 35.5,
  "cpuPercentPeak": 80,
  "dataStatus": "available",
  "diskBytesAverage": 104857600,
  "diskBytesPeak": 209715200,
  "memoryBytesAverage": 268435456,
  "memoryBytesPeak": 536870912,
  "sampleCount": 5
}

Script

Details about the script, including its ID, name, and milestone dates.

Properties

Name	Type	Description	Restrictions
container	string	The container (folder) housing the script. Accepted on create only; it is not returned when a script is read.	write-only
created	Action	When the action was performed, and details about the user who did it	read-only
description	string¦null	Description of the script
id	string	The unique identifier of the script	read-only
modified	Action	When the action was performed, and details about the user who did it	read-only
name	string	Name of the script
resourceLimits	ResourceLimits	Resource limits for script execution.	read-only
runtime	string	The runtime execution environment for the script. Only python3.13 is accepted when creating or updating a script. python3.9 is deprecated and appears only in responses for scripts that were created before the deprecation.
state	string	Whether the script is active, trashed or purged. Only active scripts can be run.	read-only

Enumerated Values

Property	Value
runtime	python3.9
runtime	python3.13
state	active
state	trashed
state	purged

Example

{
  "description": "Checks each row in a spreadsheet and hides rows with a value of zero",
  "name": "Hide Rows with Value of Zero",
  "runtime": "python3.13"
}

ScriptExecution

The properties to make available to a script run as environment variables. All property names formatted as Camel case (camelCase), Pascal case (PascalCase), Snake case (snake_case) and Kebab case (kebab-case) are converted to capitalized Snake case. For example, a property name of apiKey becomes API_KEY. Values must be strings.

Properties

None

Example

{
  "SpreadsheetId": "9ba1b5dfbd3b4c8997f309fa61180b87",
  "apiKey": "Az86pm34xyz",
  "has-changed": "true",
  "row_number": "27"
}

ScriptRun

Details about a script run, including its status, timing, and resource usage.

Properties

Name	Type	Description	Restrictions
completed	Action¦null	When the action was performed, and details about the user who did it	read-only
created	Action	When the action was performed, and details about the user who did it	read-only
dependencyState	DependencyState	Whether the run executed against an up-to-date dependency bundle, captured at run time.	read-only
durationSeconds	number	Active execution time (started to completed).	read-only
failureReason	string	A human-readable explanation of why the run failed, such as Timed out or Python failure. Present only for a failed run. Use status to determine the outcome programmatically.	read-only
id	string	The unique identifier of the run	read-only
queueDurationSeconds	number	Time spent in the queue before execution started.	read-only
resourceLimits	ResourceLimits	Snapshot of the resource limits at execution time.	read-only
resourceUsage	ResourceUsage	Resource utilization recorded while the run executed.	read-only
runtime	string	The runtime environment in which the run executed.	read-only
started	Action¦null	When the action was performed, and details about the user who did it	read-only
status	string	The current status of the run.	read-only
termination	Termination	Structured termination information for a run that ended abnormally.	read-only
totalElapsedSeconds	number	Total elapsed time from creation to completion.	read-only
type	string	Whether the run executed the script or generated its dependency bundle.	read-only

Enumerated Values

Property	Value
runtime	python3.9
runtime	python3.13
status	acknowledged
status	queued
status	started
status	completed
status	cancelled
status	failed
type	script
type	dependency

Example

{
  "completed": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V0ZVc2VyHzU1MDg3OTc0MDE4MDg4OTY"
    }
  },
  "created": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V0ZVc2VyHzU1MDg3OTc0MDE4MDg4OTY"
    }
  },
  "dependencyState": {
    "requirementsInSync": true,
    "runtimeInSync": true
  },
  "durationSeconds": 0,
  "failureReason": "Timed out",
  "id": "ae82b647-8e43-44c3-a4e7-2aa3294c87ac",
  "queueDurationSeconds": 0,
  "resourceLimits": {
    "allocatedTimeSeconds": 14400,
    "cpuCores": 1,
    "diskBytes": 2147483648,
    "memoryBytes": 1073741824,
    "terminationGracePeriodSeconds": 15
  },
  "resourceUsage": {
    "cpuPercentAverage": 35.5,
    "cpuPercentPeak": 80,
    "dataStatus": "available",
    "diskBytesAverage": 104857600,
    "diskBytesPeak": 209715200,
    "memoryBytesAverage": 268435456,
    "memoryBytesPeak": 536870912,
    "sampleCount": 5
  },
  "runtime": "python3.13",
  "started": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V0ZVc2VyHzU1MDg3OTc0MDE4MDg4OTY"
    }
  },
  "status": "acknowledged",
  "termination": {
    "code": "OUT_OF_MEMORY[SIGTERM]",
    "gracePeriodSeconds": 15,
    "message": "Script exceeded allocated memory.",
    "reason": "memory_limit_exceeded",
    "signal": "SIGTERM",
    "type": "resource_limit_exceeded"
  },
  "totalElapsedSeconds": 0,
  "type": "script"
}

ScriptRunsListResult

Returns a JSON object with data and @nextLink properties. data contains a list of ScriptRun objects, and @nextLink provides the URL to the next set of results. If there are no additional results, @nextLink doesn’t appear. If the request returns no results at all, data contains an empty array.

Properties

Name	Type	Description	Restrictions
@nextLink	string¦null	Pagination link for next set of results
data	[ScriptRun]	Details about a script run, including its status, timing, and resource usage.	required

Example

{
  "@nextLink": "<opaque_url>",
  "data": [
    {
      "completed": {
        "dateTime": "2019-10-30T15:03:27Z",
        "user": {
          "id": "V0ZVc2VyHzU1MDg3OTc0MDE4MDg4OTY"
        }
      },
      "created": {
        "dateTime": "2019-10-30T15:03:27Z",
        "user": {
          "id": "V0ZVc2VyHzU1MDg3OTc0MDE4MDg4OTY"
        }
      },
      "dependencyState": {
        "requirementsInSync": true,
        "runtimeInSync": true
      },
      "durationSeconds": 0,
      "failureReason": "Timed out",
      "id": "ae82b647-8e43-44c3-a4e7-2aa3294c87ac",
      "queueDurationSeconds": 0,
      "resourceLimits": {
        "allocatedTimeSeconds": 14400,
        "cpuCores": 1,
        "diskBytes": 2147483648,
        "memoryBytes": 1073741824,
        "terminationGracePeriodSeconds": 15
      },
      "resourceUsage": {
        "cpuPercentAverage": 35.5,
        "cpuPercentPeak": 80,
        "dataStatus": "available",
        "diskBytesAverage": 104857600,
        "diskBytesPeak": 209715200,
        "memoryBytesAverage": 268435456,
        "memoryBytesPeak": 536870912,
        "sampleCount": 5
      },
      "runtime": "python3.13",
      "started": {
        "dateTime": "2019-10-30T15:03:27Z",
        "user": {
          "id": "V0ZVc2VyHzU1MDg3OTc0MDE4MDg4OTY"
        }
      },
      "status": "acknowledged",
      "termination": {
        "code": "OUT_OF_MEMORY[SIGTERM]",
        "gracePeriodSeconds": 15,
        "message": "Script exceeded allocated memory.",
        "reason": "memory_limit_exceeded",
        "signal": "SIGTERM",
        "type": "resource_limit_exceeded"
      },
      "totalElapsedSeconds": 0,
      "type": "script"
    }
  ]
}

ScriptSource

Details about a script source file, including its ID and path.

Properties

Name	Type	Description	Restrictions
created	Action	When the source was created. Sources have no acting user, so only dateTime is populated.	read-only
id	string	The unique identifier of the source	read-only
path	string	The path of the source (including the name)
type	string	Whether the source holds editable text or binary content such as a bundle.	read-only

Enumerated Values

Property	Value
type	source
type	binary

Example

{
  "created": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V0ZVc2VyHzU1MDg3OTc0MDE4MDg4OTY"
    }
  },
  "id": "ae82b647-8e43-44c3-a4e7-2aa3294c87ac",
  "path": "/hide_values.py",
  "type": "source"
}

ScriptSourceContentUploadResponse

Contains a presigned URL that can be used to upload content to a source. The Location header also contains a URL for an Operation that can be polled to find out if the upload was successful.

Properties

Name	Type	Description	Restrictions
uploadUrl	string	The URL to make a PUT request to, to upload the source. Include the source content as the body of the request. This is a temporary URL; it should be used immediately when the response is received.

Example

{
  "uploadUrl": "string"
}

ScriptSourcesListResult

Returns a JSON object with data and @nextLink properties. data contains a list of ScriptSource objects, and @nextLink provides the URL to the next set of results. If there are no additional results, @nextLink doesn’t appear. If the request returns no results at all, data contains an empty array.

Properties

Name	Type	Description	Restrictions
@nextLink	string¦null	Pagination link for next set of results
data	[ScriptSource]	Details about a script source file, including its ID and path.	required

Example

{
  "@nextLink": "<opaque_url>",
  "data": [
    {
      "created": {
        "dateTime": "2019-10-30T15:03:27Z",
        "user": {
          "id": "V0ZVc2VyHzU1MDg3OTc0MDE4MDg4OTY"
        }
      },
      "id": "ae82b647-8e43-44c3-a4e7-2aa3294c87ac",
      "path": "/hide_values.py",
      "type": "source"
    }
  ]
}

ScriptsListResult

Returns a JSON object with data and @nextLink properties. data contains a list of Script objects, and @nextLink provides the URL to the next set of results. If there are no additional results, @nextLink doesn’t appear. If the request returns no results at all, data contains an empty array.

Properties

Name	Type	Description	Restrictions
@nextLink	string¦null	Pagination link for next set of results
data	[Script]	Details about the script, including its ID, name, and milestone dates.	required

Example

{
  "@nextLink": "<opaque_url>",
  "data": [
    {
      "description": "Checks each row in a spreadsheet and hides rows with a value of zero",
      "name": "Hide Rows with Value of Zero",
      "runtime": "python3.13"
    }
  ]
}

SourceSyncAcceptedResponse

Response body for source sync. Contains both operationLocation for polling and uploadUrl for the ZIP upload.

Properties

Name	Type	Description	Restrictions
operationLocation	string	The URL to poll for the operation result.
uploadUrl	string	The presigned URL to PUT the ZIP archive to. Use immediately.

Example

{
  "operationLocation": "https://api.app.wdesk.com/operations/128f274395254cf17eda6b3eb3d021b9",
  "uploadUrl": "string"
}

SourceSyncRequest

Options for the source sync operation.

Properties

Name	Type	Description	Restrictions
mode	string	How to apply the ZIP contents. “replace” (default) deletes existing sources not in the ZIP. “merge” only adds/updates.

Enumerated Values

Property	Value
mode	replace
mode	merge

Example

{
  "mode": "replace"
}

Termination

Structured termination information for a run that ended abnormally.

Properties

Name	Type	Description	Restrictions
code	string	Machine-readable runner code, when available.	read-only
gracePeriodSeconds	integer	Grace period allowed before forced termination, in seconds.	read-only
message	string	Human-readable termination message.	read-only
reason	string	The specific reason the run terminated.	read-only
signal	string	Signal used to terminate the run.	read-only
type	string	The category of termination.	read-only

Enumerated Values

Property	Value
code	OUT_OF_MEMORY[SIGTERM]
code	OUT_OF_DISK[SIGTERM]
code	TIMEOUT[SIGTERM]
code	OUT_OF_MEMORY[EOF]
code	SYSTEM[PANIC]
reason	memory_limit_exceeded
reason	disk_limit_exceeded
reason	allocated_time_exceeded
reason	user_cancelled
reason	out_of_memory_before_limit_detection
reason	runner_system_failure
reason	workiva_operational_action
signal	SIGINT
signal	SIGTERM
signal	SIGKILL
type	resource_limit_exceeded
type	user_cancelled
type	unexpected_termination
type	system_failure
type	workiva_stopped

Example

{
  "code": "OUT_OF_MEMORY[SIGTERM]",
  "gracePeriodSeconds": 15,
  "message": "Script exceeded allocated memory.",
  "reason": "memory_limit_exceeded",
  "signal": "SIGTERM",
  "type": "resource_limit_exceeded"
}

User

A user referenced by their unique identifier

Properties

Name	Type	Description	Restrictions
id	string	The unique identifier of the user

Example

{
  "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
}