Method: scripts.run

Runs a function in an Apps Script project. The project must be deployed for use with the Apps Script Execution API.

This method requires authorization with an OAuth 2.0 token that includes at least one of the scopes listed in the Authorization 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 project in the script editor, then select File > Project properties and click the Scopes tab.

HTTP request

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

The URL uses Google API HTTP annotation syntax.

Path parameters

Parameters
scriptId

string

The project key of the script to be executed. To find the project key, open the project in the script editor and select File > Project properties.

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.

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 a Document or a Calendar); they can only be primitive types such as string, number, array, object, or boolean. Optional.

sessionState

string

For 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 the Intent that launches the add-on. When an Android add-on is run with a session state, it gains the privileges of a bound 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, call Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState"). Optional.

devMode

boolean

If true 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 Execution API. Optional; default is false.

Response body

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

The response will not arrive until the function finishes executing. The maximum runtime is listed in the guide to limitations in Apps Script.

If the script function returns successfully, the response field will contain an ExecutionResponse object with the function's return value in the object's result field.

If the script function (or Apps Script itself) throws an exception, the error field will contain a Status object. The Status object's details field will contain an array with a single ExecutionError object that provides information about the nature of the error.

If the run call itself fails (for example, because of a malformed request or an authorization error), the method will return an HTTP response code in the 4XX range with a different format for the response body. Client libraries will automatically convert a 4XX response into an exception class.

JSON representation
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

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

string

This field is not used.

metadata

object

This field is not used.

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" }.

done

boolean

This field is not used.

Union field result. The operation result, which can be either an error or a valid response. If done == false, neither error nor response is set. If done == true, exactly one of error or response is set. result can be only one of the following:
error

object(Status)

If a run call succeeds but the script function (or Apps Script itself) throws an exception, this field will contain a Status object. The Status object's details field will contain an array with a single ExecutionError object that provides information about the nature of the error.

response

object

If the script function returns successfully, this field will contain an ExecutionResponse object with the function's return value as the object's result field.

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

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 the Auth Guide.

Status

If a run call succeeds but the script function (or Apps Script itself) throws an exception, the response body's error field will contain this Status object.

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

number

The status code. For this API, this value will always be 3, corresponding to an INVALID_ARGUMENT error.

message

string

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

details[]

object

An array that contains a single ExecutionError 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" }.

Send feedback about...

Apps Script
Apps Script