Executing Apps Script Functions

The Apps Script API (and formerly the Apps Script Execution API) allows you to remotely execute a function in a script project you have access to. Your app can call a given Apps Script function, providing it input parameters if needed, and receive a returned response.

The examples on this page illustrate how some common execution operations can be achieved with the API. For more information including special authorization requirements, see the Executing a function guide.

In these examples, the placeholders scriptId is used to indicate where you would provide the script project ID. Follow the steps below to find the script ID:

1. In the Apps Script project, at the top left, click Project Settings .
2. Next to "Script ID," click Copy.

Execute a function

The following scripts.run request calls an Apps Script function named listFolderContent, passing it the Drive folderId and an integer MAX_SIZE as arguments. The function is executed in development mode, meaning that the most recently save version of the function is executed, regardless of what version is deployed as an executable.

The request protocol is shown below. The Executing functions guide shows how to implement a run request in different languages using the Google API client libraries.

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

{
  "function": "listFolderContent",
  "parameters": [
    folderId,
    MAX_SIZE
  ],
  "devMode": true
}

The response to this request, once the called Apps Script function completes, contains the results of the execution or an error response. In this example, the function successfully returns an array of file names:

{
  "response": {
    "result": [
      "fileTitle1",
      "fileTitle2",
      "fileTitle3"
    ]
  },
}

If the function encountered an error during the Apps Script execution, the response could look like this:

{
  "response": {
    "error": {
      "code": 3,
      "message": "ScriptError",
      "details": [{
        "@type": "type.googleapis.com/google.apps.script.v1.ExecutionError",
        "errorMessage": "The script enountered an exeception it could not resolve.",
        "errorType": "ScriptError",
        "scriptStackTraceElements": [{
          "function": "listFolderContent",
          "lineNumber": 14
        }]
      }]
    }
  }
}