Create playtable run

curl --request POST \
  --url https://beta.getsales.io/playtables/v1/api/playtable-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Team-SID: <api-key>' \
  --data '
{
  "playtable_sid": "<string>",
  "field_sids": [
    "<string>"
  ],
  "scope": {
    "object_sids": [
      "<string>"
    ],
    "view_sid": "<string>",
    "exclude_object_sids": [
      "<string>"
    ],
    "filter": {
      "and": [
        {}
      ]
    }
  },
  "params": {
    "force_rerun": true,
    "format": "csv",
    "write_tool_sid": "<string>",
    "data_source_sid": "<string>"
  },
  "max_budget": 123
}
'

import requests

url = "https://beta.getsales.io/playtables/v1/api/playtable-runs"

payload = {
    "playtable_sid": "<string>",
    "field_sids": ["<string>"],
    "scope": {
        "object_sids": ["<string>"],
        "view_sid": "<string>",
        "exclude_object_sids": ["<string>"],
        "filter": { "and": [{}] }
    },
    "params": {
        "force_rerun": True,
        "format": "csv",
        "write_tool_sid": "<string>",
        "data_source_sid": "<string>"
    },
    "max_budget": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Team-SID": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Team-SID': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    playtable_sid: '<string>',
    field_sids: ['<string>'],
    scope: {
      object_sids: ['<string>'],
      view_sid: '<string>',
      exclude_object_sids: ['<string>'],
      filter: {and: [{}]}
    },
    params: {
      force_rerun: true,
      format: 'csv',
      write_tool_sid: '<string>',
      data_source_sid: '<string>'
    },
    max_budget: 123
  })
};

fetch('https://beta.getsales.io/playtables/v1/api/playtable-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://beta.getsales.io/playtables/v1/api/playtable-runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'playtable_sid' => '<string>',
    'field_sids' => [
        '<string>'
    ],
    'scope' => [
        'object_sids' => [
                '<string>'
        ],
        'view_sid' => '<string>',
        'exclude_object_sids' => [
                '<string>'
        ],
        'filter' => [
                'and' => [
                                [
                                                                
                                ]
                ]
        ]
    ],
    'params' => [
        'force_rerun' => true,
        'format' => 'csv',
        'write_tool_sid' => '<string>',
        'data_source_sid' => '<string>'
    ],
    'max_budget' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Team-SID: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://beta.getsales.io/playtables/v1/api/playtable-runs"

	payload := strings.NewReader("{\n  \"playtable_sid\": \"<string>\",\n  \"field_sids\": [\n    \"<string>\"\n  ],\n  \"scope\": {\n    \"object_sids\": [\n      \"<string>\"\n    ],\n    \"view_sid\": \"<string>\",\n    \"exclude_object_sids\": [\n      \"<string>\"\n    ],\n    \"filter\": {\n      \"and\": [\n        {}\n      ]\n    }\n  },\n  \"params\": {\n    \"force_rerun\": true,\n    \"format\": \"csv\",\n    \"write_tool_sid\": \"<string>\",\n    \"data_source_sid\": \"<string>\"\n  },\n  \"max_budget\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Team-SID", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://beta.getsales.io/playtables/v1/api/playtable-runs")
  .header("Authorization", "Bearer <token>")
  .header("Team-SID", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"playtable_sid\": \"<string>\",\n  \"field_sids\": [\n    \"<string>\"\n  ],\n  \"scope\": {\n    \"object_sids\": [\n      \"<string>\"\n    ],\n    \"view_sid\": \"<string>\",\n    \"exclude_object_sids\": [\n      \"<string>\"\n    ],\n    \"filter\": {\n      \"and\": [\n        {}\n      ]\n    }\n  },\n  \"params\": {\n    \"force_rerun\": true,\n    \"format\": \"csv\",\n    \"write_tool_sid\": \"<string>\",\n    \"data_source_sid\": \"<string>\"\n  },\n  \"max_budget\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://beta.getsales.io/playtables/v1/api/playtable-runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Team-SID"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"playtable_sid\": \"<string>\",\n  \"field_sids\": [\n    \"<string>\"\n  ],\n  \"scope\": {\n    \"object_sids\": [\n      \"<string>\"\n    ],\n    \"view_sid\": \"<string>\",\n    \"exclude_object_sids\": [\n      \"<string>\"\n    ],\n    \"filter\": {\n      \"and\": [\n        {}\n      ]\n    }\n  },\n  \"params\": {\n    \"force_rerun\": true,\n    \"format\": \"csv\",\n    \"write_tool_sid\": \"<string>\",\n    \"data_source_sid\": \"<string>\"\n  },\n  \"max_budget\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "operation": "create",
  "item": {
    "sid": "<string>",
    "team_sid": "<string>",
    "playtable_sid": "<string>",
    "object_type": "people",
    "type": "enrich",
    "field_sids": [
      "<string>"
    ],
    "scope": {
      "object_sids": [
        "<string>"
      ],
      "view_sid": "<string>",
      "filter": {
        "and": [
          {}
        ]
      }
    },
    "params_snapshot": {},
    "max_budget": 123,
    "estimated_cost": 123,
    "file_url": "<string>",
    "created_by": {
      "actor_type": "user",
      "actor_sid": "<string>",
      "team_sid": "<string>",
      "permissions": {},
      "actor_name": "<string>",
      "oauth_client_sid": "<string>",
      "reason": "<string>",
      "cluster_id": 123,
      "trace_id": "<string>"
    },
    "created_at": "<string>",
    "finished_at": "<string>"
  },
  "already_exists": true,
  "meta": {
    "trace_id": "<string>",
    "span_id": "<string>",
    "timestamp": "<string>",
    "duration_ms": 1,
    "team_sid": "<string>",
    "actor_type": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "<string>",
    "recoverable": true,
    "suggestion": "<string>",
    "field_errors": {},
    "blockers": [
      {
        "type": "<string>",
        "severity": "hard",
        "description": "<string>",
        "entity_sid": "<string>",
        "resolution": "<string>",
        "resolution_hint": "<string>",
        "count": 123
      }
    ],
    "context": {}
  },
  "meta": {
    "trace_id": "<string>",
    "span_id": "<string>",
    "timestamp": "<string>",
    "duration_ms": 1,
    "team_sid": "<string>",
    "actor_type": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "<string>",
    "recoverable": true,
    "suggestion": "<string>",
    "field_errors": {},
    "blockers": [
      {
        "type": "<string>",
        "severity": "hard",
        "description": "<string>",
        "entity_sid": "<string>",
        "resolution": "<string>",
        "resolution_hint": "<string>",
        "count": 123
      }
    ],
    "context": {}
  },
  "meta": {
    "trace_id": "<string>",
    "span_id": "<string>",
    "timestamp": "<string>",
    "duration_ms": 1,
    "team_sid": "<string>",
    "actor_type": "<string>"
  }
}

playtable_runs

Create playtable run

The single entry point for every bulk operation on a playtable. Async: the created row is the progress handle: poll get_playtable_run with include progress every ~5s until progress.state is finished or cancelled.

type branches the body. enrich is the only paid type (action columns over the scope; a formula column never runs, it fills through backfill_playtable_field): always estimate_playtable_run first, tell the user the cost range and set max_budget to its cost_max (exhaustion auto-cancels, reason budget_exhausted; a cap at cost_expected cancels a row short); params force_rerun re-queues done cells (re-charge consent), params cells not_run | error narrows to those. export writes the scope to CSV (params format csv, a file_url) or an external tool (write_tool_sid). import batch-promotes a data source (params data_source_sid, no scope). bulk runs tag, field, workflow, move and delete edits (params operation).

scope, required for enrich, export and bulk: one form, object_sids or view_sid/filter; an empty filter is rejected, the scope is snapshotted at create; hand-picked object_sids and exclude_object_sids are capped at 10 000 each (422 scope_too_large). 409 conflict when a field already has an active run (its sid in error.context), 429 at the team concurrency cap; already_exists is always false. When NOT: single-cell fixes (update_playtable_field_value); continuous source syncing (data sources; import here is a one-shot promotion).

Contract:

MCP tool create_playtable_run, registry package mcp.playtables/playtable_runs, mount playtables.columns.
Operation create, response envelope create.
Flags: none.

POST

api

playtable-runs

Create playtable run

curl --request POST \
  --url https://beta.getsales.io/playtables/v1/api/playtable-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Team-SID: <api-key>' \
  --data '
{
  "playtable_sid": "<string>",
  "field_sids": [
    "<string>"
  ],
  "scope": {
    "object_sids": [
      "<string>"
    ],
    "view_sid": "<string>",
    "exclude_object_sids": [
      "<string>"
    ],
    "filter": {
      "and": [
        {}
      ]
    }
  },
  "params": {
    "force_rerun": true,
    "format": "csv",
    "write_tool_sid": "<string>",
    "data_source_sid": "<string>"
  },
  "max_budget": 123
}
'

import requests

url = "https://beta.getsales.io/playtables/v1/api/playtable-runs"

payload = {
    "playtable_sid": "<string>",
    "field_sids": ["<string>"],
    "scope": {
        "object_sids": ["<string>"],
        "view_sid": "<string>",
        "exclude_object_sids": ["<string>"],
        "filter": { "and": [{}] }
    },
    "params": {
        "force_rerun": True,
        "format": "csv",
        "write_tool_sid": "<string>",
        "data_source_sid": "<string>"
    },
    "max_budget": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Team-SID": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Team-SID': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    playtable_sid: '<string>',
    field_sids: ['<string>'],
    scope: {
      object_sids: ['<string>'],
      view_sid: '<string>',
      exclude_object_sids: ['<string>'],
      filter: {and: [{}]}
    },
    params: {
      force_rerun: true,
      format: 'csv',
      write_tool_sid: '<string>',
      data_source_sid: '<string>'
    },
    max_budget: 123
  })
};

fetch('https://beta.getsales.io/playtables/v1/api/playtable-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://beta.getsales.io/playtables/v1/api/playtable-runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'playtable_sid' => '<string>',
    'field_sids' => [
        '<string>'
    ],
    'scope' => [
        'object_sids' => [
                '<string>'
        ],
        'view_sid' => '<string>',
        'exclude_object_sids' => [
                '<string>'
        ],
        'filter' => [
                'and' => [
                                [
                                                                
                                ]
                ]
        ]
    ],
    'params' => [
        'force_rerun' => true,
        'format' => 'csv',
        'write_tool_sid' => '<string>',
        'data_source_sid' => '<string>'
    ],
    'max_budget' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Team-SID: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://beta.getsales.io/playtables/v1/api/playtable-runs"

	payload := strings.NewReader("{\n  \"playtable_sid\": \"<string>\",\n  \"field_sids\": [\n    \"<string>\"\n  ],\n  \"scope\": {\n    \"object_sids\": [\n      \"<string>\"\n    ],\n    \"view_sid\": \"<string>\",\n    \"exclude_object_sids\": [\n      \"<string>\"\n    ],\n    \"filter\": {\n      \"and\": [\n        {}\n      ]\n    }\n  },\n  \"params\": {\n    \"force_rerun\": true,\n    \"format\": \"csv\",\n    \"write_tool_sid\": \"<string>\",\n    \"data_source_sid\": \"<string>\"\n  },\n  \"max_budget\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Team-SID", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://beta.getsales.io/playtables/v1/api/playtable-runs")
  .header("Authorization", "Bearer <token>")
  .header("Team-SID", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"playtable_sid\": \"<string>\",\n  \"field_sids\": [\n    \"<string>\"\n  ],\n  \"scope\": {\n    \"object_sids\": [\n      \"<string>\"\n    ],\n    \"view_sid\": \"<string>\",\n    \"exclude_object_sids\": [\n      \"<string>\"\n    ],\n    \"filter\": {\n      \"and\": [\n        {}\n      ]\n    }\n  },\n  \"params\": {\n    \"force_rerun\": true,\n    \"format\": \"csv\",\n    \"write_tool_sid\": \"<string>\",\n    \"data_source_sid\": \"<string>\"\n  },\n  \"max_budget\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://beta.getsales.io/playtables/v1/api/playtable-runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Team-SID"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"playtable_sid\": \"<string>\",\n  \"field_sids\": [\n    \"<string>\"\n  ],\n  \"scope\": {\n    \"object_sids\": [\n      \"<string>\"\n    ],\n    \"view_sid\": \"<string>\",\n    \"exclude_object_sids\": [\n      \"<string>\"\n    ],\n    \"filter\": {\n      \"and\": [\n        {}\n      ]\n    }\n  },\n  \"params\": {\n    \"force_rerun\": true,\n    \"format\": \"csv\",\n    \"write_tool_sid\": \"<string>\",\n    \"data_source_sid\": \"<string>\"\n  },\n  \"max_budget\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "operation": "create",
  "item": {
    "sid": "<string>",
    "team_sid": "<string>",
    "playtable_sid": "<string>",
    "object_type": "people",
    "type": "enrich",
    "field_sids": [
      "<string>"
    ],
    "scope": {
      "object_sids": [
        "<string>"
      ],
      "view_sid": "<string>",
      "filter": {
        "and": [
          {}
        ]
      }
    },
    "params_snapshot": {},
    "max_budget": 123,
    "estimated_cost": 123,
    "file_url": "<string>",
    "created_by": {
      "actor_type": "user",
      "actor_sid": "<string>",
      "team_sid": "<string>",
      "permissions": {},
      "actor_name": "<string>",
      "oauth_client_sid": "<string>",
      "reason": "<string>",
      "cluster_id": 123,
      "trace_id": "<string>"
    },
    "created_at": "<string>",
    "finished_at": "<string>"
  },
  "already_exists": true,
  "meta": {
    "trace_id": "<string>",
    "span_id": "<string>",
    "timestamp": "<string>",
    "duration_ms": 1,
    "team_sid": "<string>",
    "actor_type": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "<string>",
    "recoverable": true,
    "suggestion": "<string>",
    "field_errors": {},
    "blockers": [
      {
        "type": "<string>",
        "severity": "hard",
        "description": "<string>",
        "entity_sid": "<string>",
        "resolution": "<string>",
        "resolution_hint": "<string>",
        "count": 123
      }
    ],
    "context": {}
  },
  "meta": {
    "trace_id": "<string>",
    "span_id": "<string>",
    "timestamp": "<string>",
    "duration_ms": 1,
    "team_sid": "<string>",
    "actor_type": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "<string>",
    "recoverable": true,
    "suggestion": "<string>",
    "field_errors": {},
    "blockers": [
      {
        "type": "<string>",
        "severity": "hard",
        "description": "<string>",
        "entity_sid": "<string>",
        "resolution": "<string>",
        "resolution_hint": "<string>",
        "count": 123
      }
    ],
    "context": {}
  },
  "meta": {
    "trace_id": "<string>",
    "span_id": "<string>",
    "timestamp": "<string>",
    "duration_ms": 1,
    "team_sid": "<string>",
    "actor_type": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Access token issued by gs.service.id. Its access_identity claim carries team_sid, actor_sid and actor_type, and that team scope is authoritative.

Team-SID

string

header

required

Team scope for tokens that do not carry one. Ignored when the token already names a team.

Body

application/json

Request body of create_playtable_run.

playtable_sid

string

required

Parent playtable sid (pt_tb_…).

Required string length: 18

Pattern: ^pt_tb_

object_type

enum<string>

required

Which tab the run targets: people | company.

Available options:

people,

company

type

enum<string>

required

enrich (PAID - estimate first, set max_budget) | export | import | bulk. Branches which fields below are required.

Available options:

enrich,

export,

import,

bulk

field_sids

string[]

REQUIRED for type=enrich, forbidden otherwise (422): 1..20 action columns (a widget, a plain column or a formula column is 422; a formula column fills through backfill_playtable_field instead).

Required array length: 1 - 20 elements

Required string length: 18

Pattern: ^pt_fd_

scope

object

REQUIRED for enrich | export | bulk, forbidden for import (422). Exactly one form: object_sids XOR view_sid/filter.

Show child attributes

params

object

Type-specific params, snapshotted into params_snapshot: enrich {force_rerun?, cells?}; export {format:"csv"} or {write_tool_sid}; import {data_source_sid}; bulk {operation, …op payload}.

Show child attributes

max_budget

number | null

Decimal credits - enrich only: hard per-run spend cap; the budget guard cancels the run when exhausted (reason=budget_exhausted). Omit/null = uncapped. Base it on the estimate cost range.

Response

create success envelope.

success

enum<boolean>

required

Available options:

true

operation

enum<string>

required

Available options:

create

item

object

required

Show child attributes

already_exists

boolean

required

Overview

Playtables API

Unibox API

Signals API

Integrations API

ID and Teams API

Create playtable run

Authorizations

Body

Response