Method: scripts.run

  • Thescripts.run method in the Apps Script API allows you to execute a function within a deployed Apps Script project.

  • This method requires authorization using an OAuth 2.0 token with appropriate scopes.

  • The HTTP request uses a POST method with the script ID as a path parameter.

  • The request body specifies the function name to execute and optional parameters.

  • The response body indicates the execution status, including success with a result or failure with an error.

Runs a function in an Apps Script project. The script project must be deployed for use with the Apps Script API and the calling application must share the same Cloud Platform project.

This method requires authorization with an OAuth 2.0 token that includes at least one of the scopes listed in theAuthorization section; script projects that do not require authorization cannot be executed through this API. To find the correct scopes to include in the authentication token, open the script projectOverview page and scroll down to "Project OAuth Scopes."

The error403, PERMISSION_DENIED: The caller does not have permission indicates that the Cloud Platform project used to authorize the request is not the same as the one used by the script.

HTTP request

POST https://script.googleapis.com/v1/scripts/{deploymentId}:run

The URL usesgRPC Transcoding syntax.

Path parameters

Parameters
deploymentId

string

The deployment ID for the API Executable deployment.Find the deployment ID underDeploy > Manage deployments in the script editor.

Request body

The request body contains data with the following structure:

JSON representation
{"function":string,"parameters":[value],"sessionState":string,"devMode":boolean}
Fields
function

string

The name of the function to execute in the given script. The name does not include parentheses or parameters. It can reference a function in an included library such asLibrary.libFunction1.

parameters[]

value (Value format)

The parameters to be passed to the function being executed. The object type for each parameter should match the expected type in Apps Script. Parameters cannot be Apps Script-specific object types (such as aDocument or aCalendar); they can only be primitive types such asstring,number,array,object, orboolean. Optional.

sessionState

string

Deprecated. For use with Android add-ons only. An ID that represents the user's current session in the Android app for Google Docs or Sheets, included as extra data in theIntent that launches the add-on. When an Android add-on is run with a session state, it gains the privileges of abound script—that is, it can access information like the user's current cursor position (in Docs) or selected cell (in Sheets). To retrieve the state, callIntent.getStringExtra("com.google.android.apps.docs.addons.SessionState"). Optional.

devMode

boolean

Iftrue and the user is an owner of the script, the script runs at the most recently saved version rather than the version deployed for use with the Apps Script API. Optional; default isfalse.

Response body

If successful, the response body contains data with the following structure:

A representation of an execution of an Apps Script function started withrun. The execution response does not arrive until the function finishes executing. The maximum execution runtime is listed in theApps Script quotas guide.

After execution has started, it can have one of four outcomes:

  • If the script function returns successfully, theresponse field contains anExecutionResponse object with the function's return value in the object'sresult field.
  • If the script function (or Apps Script itself) throws an exception, theerror field contains aStatus object. TheStatus object'sdetails field contains an array with a singleExecutionError object that provides information about the nature of the error.
  • If the execution has not yet completed, thedone field isfalse and the neither theresponse norerror fields are present.
  • If therun call itself fails (for example, because of a malformed request or an authorization error), the method returns an HTTP response code in the 4XX range with a different format for the response body. Client libraries automatically convert a 4XX response into an exception class.

JSON representation
{"done":boolean,// Union fieldresult can be only one of the following:"error":{object (Status)},"response":{"@type":string,field1:...,...}// End of list of possible types for union fieldresult.}
Fields
done

boolean

This field indicates whether the script execution has completed. A completed execution has a populatedresponse field containing theExecutionResponse from function that was executed.

Union fieldresult. The operation result, which can be either anerror or a validresponse. Ifdone ==false, neithererror norresponse is set. Ifdone ==true, exactly one oferror orresponse may be set. Some services might not provide the result.result can be only one of the following:
error

object (Status)

If arun call succeeds but the script function (or Apps Script itself) throws an exception, this field contains aStatus object. TheStatus object'sdetails field contains an array with a singleExecutionError object that provides information about the nature of the error.

response

object

If the script function returns successfully, this field contains anExecutionResponse object with the function's return value.

An object containing fields of an arbitrary type. An additional field"@type" contains a URI identifying the type. Example:{ "id": 1234, "@type": "types.example.com/standard/id" }.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://apps-apis.google.com/a/feeds
  • https://apps-apis.google.com/a/feeds/alias/
  • https://apps-apis.google.com/a/feeds/groups/
  • https://mail.google.com/
  • https://sites.google.com/feeds
  • https://www.google.com/calendar/feeds
  • https://www.google.com/m8/feeds
  • https://www.googleapis.com/auth/admin.directory.group
  • https://www.googleapis.com/auth/admin.directory.user
  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/dynamiccreatives
  • https://www.googleapis.com/auth/forms
  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/groups
  • https://www.googleapis.com/auth/script.cpanel
  • https://www.googleapis.com/auth/script.external_request
  • https://www.googleapis.com/auth/script.scriptapp
  • https://www.googleapis.com/auth/script.send_mail
  • https://www.googleapis.com/auth/script.storage
  • https://www.googleapis.com/auth/script.webapp.deploy
  • https://www.googleapis.com/auth/spreadsheets
  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/sqlservice
  • https://www.googleapis.com/auth/userinfo.email

For more information, see theOAuth 2.0 Overview.

Status

If arun call succeeds but the script function (or Apps Script itself) throws an exception, the response body'serror field contains thisStatus object.

JSON representation
{"code":integer,"message":string,"details":[{"@type":string,field1:...,...}]}
Fields
code

integer

The status code. For this API, this value either:

  • 10, indicating aSCRIPT_TIMEOUT error,
  • 3, indicating anINVALID_ARGUMENT error, or
  • 1, indicating aCANCELLED execution.

message

string

A developer-facing error message, which is in English. Any user-facing error message is localized and sent in thedetails field, or localized by the client.

details[]

object

An array that contains a singleExecutionError object that provides information about the nature of the error.

An object containing fields of an arbitrary type. An additional field"@type" contains a URI identifying the type. Example:{ "id": 1234, "@type": "types.example.com/standard/id" }.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-04 UTC.