Skip to main content

​
Overview

The Script API lets you:
  • List and view workflows in your account
  • Run workflows with custom inputs (single or batch)
  • Monitor executions and retrieve results

​
Base URL

https://script.so/api/v1

​
Authentication

All endpoints require an API key passed in the x-api-key header. Get your API key from Profile. 
curl https://script.so/api/v1/workflows \
  -H "x-api-key: YOUR_API_KEY"

​
Quick Start

​
1. List your workflows

curl https://script.so/api/v1/workflows \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Send welcome email",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "cursor": null
}

​
2. Get workflow details

Retrieve a workflow to see its input schema: 
curl https://script.so/api/v1/workflows/{workflowId} \
  -H "x-api-key: YOUR_API_KEY"

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Send welcome email",
  "description": "Sends a personalized welcome email to new users",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "input_schema": {
    "type": "object",
    "properties": {
      "email": { "type": "string" },
      "name": { "type": "string" }
    },
    "required": ["email"]
  }
}

​
3. Run a workflow

curl -X POST https://script.so/api/v1/workflows/{workflowId}/executions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"email": "john@example.com", "name": "John"}}'

{
  "execution_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "initial",
  "created_at": "2024-01-15T10:35:00Z"
}

​
4. Check execution status and get results

Poll the execution endpoint until status is finished: 
curl https://script.so/api/v1/workflows/{workflowId}/executions/{executionId} \
  -H "x-api-key: YOUR_API_KEY"

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "finished",
  "created_at": "2024-01-15T10:35:00Z",
  "results": [
    {
      "filename": "result.json",
      "url": "https://storage.script.so/results/abc123?token=xyz"
    }
  ]
}
Results are returned as presigned URLs that expire in 1 hour.

​
Batch Executions

Run a workflow multiple times with different inputs in a single request: 
curl -X POST https://script.so/api/v1/workflows/{workflowId}/executions/batch \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"email": "alice@example.com", "name": "Alice"},
      {"email": "bob@example.com", "name": "Bob"}
    ],
    "concurrency": "medium"
  }'

{
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "total": 2,
  "executions": [
    {"execution_id": "aaa-111", "index": 0},
    {"execution_id": "bbb-222", "index": 1}
  ]
}
Concurrency levels: low (1), medium (5), high (15).

​
Execution Status

StatusDescription
initialExecution created, not yet started
processingCurrently running
human_in_the_loopWaiting for human approval
finishedCompleted successfully
errorExecution failed

​
Pagination

List endpoints return paginated results with a cursor field: 
# First page
curl "https://script.so/api/v1/workflows?limit=10"

# Next page (URL-encode the cursor value)
curl "https://script.so/api/v1/workflows?limit=10&cursor=2024-01-15T10%3A30%3A00Z"
When cursor is null, there are no more results.

​
Limitations

LimitValueDescription
Request body size4 MBMaximum size for request payloads
Rate limiting100/minRequests per minute per API key
Pagination limit100 itemsMaximum items returned per list request
Execution timeout15 minutesMaximum runtime for a single workflow execution
Concurrent executions10Maximum concurrent executions per workflow
Batch size10,000Maximum items per batch execution request

​
Errors

CodeDescription
400Bad request — check your parameters
401Unauthorized — invalid or missing API key
404Not found — resource doesn’t exist
429Rate limited — slow down
500Server error — try again later
Error responses include a message: 
{
  "error": "Workflow not found"
}