Skip to content
rowlab Docs

Create Run

POST
/v1/datasets/{dataset_id}/runs
curl --request POST \
  --url https://example.com/v1/datasets/example/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "sql": "SELECT * FROM data", "tasks": [ { "id": "example", "template": "", "type": "yes_no", "preset": "summarize", "column": "answer", "extraction_mode": "single", "options": [], "fields": [], "reason": false, "models": [ "typesafe/jev-1.14" ] } ] }'

Queue a run of every task with every model on the rows in the scope (all rows if none is given). It makes a new dataset (dataset_id), created right away with every row; the answer columns of the rows in scope fill in as the run works through them in the background: poll GET /v1/runs/{id} for its progress. Answers already given are free: they come from the response cache.

A task needs only its template and type; the result column and models default to ones that suit the type (see GET /v1/utils/task-types).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
dataset_id
required
Dataset Id
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
RunRequest

What to run: the tasks, on the rows a query picks.

object
sql
Sql

Which rows to ask about: a SELECT over data returning __row_id; all rows by default.

string
default: SELECT * FROM data
tasks
required
Tasks
Array<object>
Task
object
id
Id
string
template
Template

The prompt, e.g. “Is this review negative? {{review}}”.

string
""
type
Type
string
default: yes_no
Allowed values: yes_no pick_one pick_any scale extract write
preset
Any of:
string
Allowed values: summarize translate
column
Column

Base name of the result columns. Defaults to one for the type.

string
default: answer
extraction_mode
Extraction Mode

Extraction editor: one scalar value or named, typed fields.

string
default: structure
Allowed values: single structure
options
Options

The choices for pick one and pick any; the levels, lowest first, for scale.

Array<object>
default:
Option
object
name
required
Name
string
description
Description
string
""
fields
Fields

For extract: what to pull out. "amount:number" is short for {"name": "amount", "type": "number"}.

Array<object>
default:
ExtractField
object
name
required
Name
string
type
Type
string
default: text
Allowed values: text number boolean date list items
description
Description

What to put in it, if the name doesn’t say.

string
""
fields
Array<object> recursive
reason
Reason

Also write why, from LLMs, for classify and extract.

boolean
models
Models

Decision models or LLMs; see GET /v1/utils/models. Defaults to one for the type.

Array<string>
default: typesafe/jev-1.14

Responses

Section titled “Responses”

201

Section titled “201”

Successful Response

Media typeapplication/json
Run
object
id
required
Id
string
dataset_id
required
Dataset Id

The dataset it makes.

string
status
required
Status
string
Allowed values: queued running stopping stopped done failed
config
required
RunRequest

The query and tasks it was started with.

object
sql
Sql

Which rows to ask about: a SELECT over data returning __row_id; all rows by default.

string
default: SELECT * FROM data
tasks
required
Tasks
Array<object>
Task
object
id
required
Id
string
template
required
Template

The prompt, e.g. “Is this review negative? {{review}}”.

string
""
type
required
Type
string
default: yes_no
Allowed values: yes_no pick_one pick_any scale extract write
preset
required
Any of:
string
Allowed values: summarize translate
column
required
Column

Base name of the result columns. Defaults to one for the type.

string
default: answer
extraction_mode
required
Extraction Mode

Extraction editor: one scalar value or named, typed fields.

string
default: structure
Allowed values: single structure
options
required
Options

The choices for pick one and pick any; the levels, lowest first, for scale.

Array<object>
default:
Option
object
name
required
Name
string
description
Description
string
""
fields
required
Fields

For extract: what to pull out. "amount:number" is short for {"name": "amount", "type": "number"}.

Array<object>
default:
ExtractField
object
name
required
Name
string
type
required
Type
string
default: text
Allowed values: text number boolean date list items
description
required
Description

What to put in it, if the name doesn’t say.

string
""
fields
required
Array<object> recursive
reason
required
Reason

Also write why, from LLMs, for classify and extract.

boolean
models
required
Models

Decision models or LLMs; see GET /v1/utils/models. Defaults to one for the type.

Array<string>
default: typesafe/jev-1.14
columns
required
Columns

The answer columns, each with a _proba column.

Array<string>
costs
required
Costs

Per task and model, so far.

Array<object>
TaskModelCost
object
task_id
required
Task Id
string
model
required
Model
string
cost
required
Cost

USD spent by this run; cached answers are free.

number
failed
required
Failed

Rows without an answer.

integer
row_count
required
Row Count

Rows it asks about: the rows in its scope.

integer
next_chunk
required
Next Chunk

The first chunk of rows not yet written.

integer
done
required
Done

Model calls answered (or failed) so far.

integer
total
required
Total

Model calls the run makes.

integer
cost
required
Cost

USD spent so far; cached answers are free.

number
error
required
Any of:
string
created_by
required
Any of:
string
created_at
required
Created At
string format: date-time
updated_at
required
Any of:
string format: date-time

Example 

{
  "status": "queued",
  "config": {
    "sql": "SELECT * FROM data",
    "tasks": [
      {
        "template": "",
        "type": "yes_no",
        "preset": "summarize",
        "column": "answer",
        "extraction_mode": "single",
        "options": [],
        "fields": [],
        "reason": false,
        "models": [
          "typesafe/jev-1.14"
        ]
      }
    ]
  }
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object

Example generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}