Run one canvas tile with the canvas filters that …
curl --request POST \
--url https://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run \
--header 'Content-Type: application/json' \
--header 'authorization: <api-key>' \
--data '
{
"apiKey": "<string>",
"organizationId": "<string>",
"connectionId": "<string>",
"tz": 123,
"forProjectUserId": "<string>",
"dataModelVersion": 123,
"canvasVersion": 123,
"filterValues": [
{
"filterId": "<string>",
"selectedValue": "<unknown>"
}
],
"adhocFilters": [
{
"field": "<string>",
"displayName": "<string>",
"fieldKeys": [
"<string>"
],
"itemIds": [
"<string>"
],
"selectedValue": "<string>"
}
]
}
'import requests
url = "https://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run"
payload = {
"apiKey": "<string>",
"organizationId": "<string>",
"connectionId": "<string>",
"tz": 123,
"forProjectUserId": "<string>",
"dataModelVersion": 123,
"canvasVersion": 123,
"filterValues": [
{
"filterId": "<string>",
"selectedValue": "<unknown>"
}
],
"adhocFilters": [
{
"field": "<string>",
"displayName": "<string>",
"fieldKeys": ["<string>"],
"itemIds": ["<string>"],
"selectedValue": "<string>"
}
]
}
headers = {
"authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
apiKey: '<string>',
organizationId: '<string>',
connectionId: '<string>',
tz: 123,
forProjectUserId: '<string>',
dataModelVersion: 123,
canvasVersion: 123,
filterValues: [{filterId: '<string>', selectedValue: '<unknown>'}],
adhocFilters: [
{
field: '<string>',
displayName: '<string>',
fieldKeys: ['<string>'],
itemIds: ['<string>'],
selectedValue: '<string>'
}
]
})
};
fetch('https://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run', 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://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run",
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([
'apiKey' => '<string>',
'organizationId' => '<string>',
'connectionId' => '<string>',
'tz' => 123,
'forProjectUserId' => '<string>',
'dataModelVersion' => 123,
'canvasVersion' => 123,
'filterValues' => [
[
'filterId' => '<string>',
'selectedValue' => '<unknown>'
]
],
'adhocFilters' => [
[
'field' => '<string>',
'displayName' => '<string>',
'fieldKeys' => [
'<string>'
],
'itemIds' => [
'<string>'
],
'selectedValue' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <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://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run"
payload := strings.NewReader("{\n \"apiKey\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"connectionId\": \"<string>\",\n \"tz\": 123,\n \"forProjectUserId\": \"<string>\",\n \"dataModelVersion\": 123,\n \"canvasVersion\": 123,\n \"filterValues\": [\n {\n \"filterId\": \"<string>\",\n \"selectedValue\": \"<unknown>\"\n }\n ],\n \"adhocFilters\": [\n {\n \"field\": \"<string>\",\n \"displayName\": \"<string>\",\n \"fieldKeys\": [\n \"<string>\"\n ],\n \"itemIds\": [\n \"<string>\"\n ],\n \"selectedValue\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<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://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run")
.header("authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"apiKey\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"connectionId\": \"<string>\",\n \"tz\": 123,\n \"forProjectUserId\": \"<string>\",\n \"dataModelVersion\": 123,\n \"canvasVersion\": 123,\n \"filterValues\": [\n {\n \"filterId\": \"<string>\",\n \"selectedValue\": \"<unknown>\"\n }\n ],\n \"adhocFilters\": [\n {\n \"field\": \"<string>\",\n \"displayName\": \"<string>\",\n \"fieldKeys\": [\n \"<string>\"\n ],\n \"itemIds\": [\n \"<string>\"\n ],\n \"selectedValue\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"apiKey\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"connectionId\": \"<string>\",\n \"tz\": 123,\n \"forProjectUserId\": \"<string>\",\n \"dataModelVersion\": 123,\n \"canvasVersion\": 123,\n \"filterValues\": [\n {\n \"filterId\": \"<string>\",\n \"selectedValue\": \"<unknown>\"\n }\n ],\n \"adhocFilters\": [\n {\n \"field\": \"<string>\",\n \"displayName\": \"<string>\",\n \"fieldKeys\": [\n \"<string>\"\n ],\n \"itemIds\": [\n \"<string>\"\n ],\n \"selectedValue\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"data": {
"message": "<string>",
"queryResult": [
{}
],
"filterCoverage": {
"applied": [
{
"filterId": "<string>",
"displayName": "<string>",
"fieldKey": "<string>",
"appliesAs": "raw"
}
],
"skipped": [
{
"filterId": "<string>",
"displayName": "<string>",
"fieldKey": "<string>",
"reason": "<string>"
}
]
},
"error": "<string>",
"unauthorizedTables": [
"<string>"
],
"profiling": {
"profile_breakdown": {},
"compiled_sql": "<string>",
"original_sql": "<string>"
},
"truncated": true,
"needsConnection": {
"connectorId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"connectorName": "<string>",
"action": "connect_oauth"
}
}
}{
"status": "error",
"error": {
"message": "<string>",
"code": "<string>",
"details": {}
}
}Canvases
Run Canvas Item
Run one canvas tile with the canvas filters that reach it, and report which filters applied
POST
/
v2
/
api
/
projects
/
{projectId}
/
workspaces
/
{workspaceId}
/
canvases
/
{canvasId}
/
items
/
{itemId}
/
run
Run one canvas tile with the canvas filters that …
curl --request POST \
--url https://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run \
--header 'Content-Type: application/json' \
--header 'authorization: <api-key>' \
--data '
{
"apiKey": "<string>",
"organizationId": "<string>",
"connectionId": "<string>",
"tz": 123,
"forProjectUserId": "<string>",
"dataModelVersion": 123,
"canvasVersion": 123,
"filterValues": [
{
"filterId": "<string>",
"selectedValue": "<unknown>"
}
],
"adhocFilters": [
{
"field": "<string>",
"displayName": "<string>",
"fieldKeys": [
"<string>"
],
"itemIds": [
"<string>"
],
"selectedValue": "<string>"
}
]
}
'import requests
url = "https://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run"
payload = {
"apiKey": "<string>",
"organizationId": "<string>",
"connectionId": "<string>",
"tz": 123,
"forProjectUserId": "<string>",
"dataModelVersion": 123,
"canvasVersion": 123,
"filterValues": [
{
"filterId": "<string>",
"selectedValue": "<unknown>"
}
],
"adhocFilters": [
{
"field": "<string>",
"displayName": "<string>",
"fieldKeys": ["<string>"],
"itemIds": ["<string>"],
"selectedValue": "<string>"
}
]
}
headers = {
"authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
apiKey: '<string>',
organizationId: '<string>',
connectionId: '<string>',
tz: 123,
forProjectUserId: '<string>',
dataModelVersion: 123,
canvasVersion: 123,
filterValues: [{filterId: '<string>', selectedValue: '<unknown>'}],
adhocFilters: [
{
field: '<string>',
displayName: '<string>',
fieldKeys: ['<string>'],
itemIds: ['<string>'],
selectedValue: '<string>'
}
]
})
};
fetch('https://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run', 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://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run",
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([
'apiKey' => '<string>',
'organizationId' => '<string>',
'connectionId' => '<string>',
'tz' => 123,
'forProjectUserId' => '<string>',
'dataModelVersion' => 123,
'canvasVersion' => 123,
'filterValues' => [
[
'filterId' => '<string>',
'selectedValue' => '<unknown>'
]
],
'adhocFilters' => [
[
'field' => '<string>',
'displayName' => '<string>',
'fieldKeys' => [
'<string>'
],
'itemIds' => [
'<string>'
],
'selectedValue' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <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://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run"
payload := strings.NewReader("{\n \"apiKey\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"connectionId\": \"<string>\",\n \"tz\": 123,\n \"forProjectUserId\": \"<string>\",\n \"dataModelVersion\": 123,\n \"canvasVersion\": 123,\n \"filterValues\": [\n {\n \"filterId\": \"<string>\",\n \"selectedValue\": \"<unknown>\"\n }\n ],\n \"adhocFilters\": [\n {\n \"field\": \"<string>\",\n \"displayName\": \"<string>\",\n \"fieldKeys\": [\n \"<string>\"\n ],\n \"itemIds\": [\n \"<string>\"\n ],\n \"selectedValue\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<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://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run")
.header("authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"apiKey\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"connectionId\": \"<string>\",\n \"tz\": 123,\n \"forProjectUserId\": \"<string>\",\n \"dataModelVersion\": 123,\n \"canvasVersion\": 123,\n \"filterValues\": [\n {\n \"filterId\": \"<string>\",\n \"selectedValue\": \"<unknown>\"\n }\n ],\n \"adhocFilters\": [\n {\n \"field\": \"<string>\",\n \"displayName\": \"<string>\",\n \"fieldKeys\": [\n \"<string>\"\n ],\n \"itemIds\": [\n \"<string>\"\n ],\n \"selectedValue\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/items/{itemId}/run")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"apiKey\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"connectionId\": \"<string>\",\n \"tz\": 123,\n \"forProjectUserId\": \"<string>\",\n \"dataModelVersion\": 123,\n \"canvasVersion\": 123,\n \"filterValues\": [\n {\n \"filterId\": \"<string>\",\n \"selectedValue\": \"<unknown>\"\n }\n ],\n \"adhocFilters\": [\n {\n \"field\": \"<string>\",\n \"displayName\": \"<string>\",\n \"fieldKeys\": [\n \"<string>\"\n ],\n \"itemIds\": [\n \"<string>\"\n ],\n \"selectedValue\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"data": {
"message": "<string>",
"queryResult": [
{}
],
"filterCoverage": {
"applied": [
{
"filterId": "<string>",
"displayName": "<string>",
"fieldKey": "<string>",
"appliesAs": "raw"
}
],
"skipped": [
{
"filterId": "<string>",
"displayName": "<string>",
"fieldKey": "<string>",
"reason": "<string>"
}
]
},
"error": "<string>",
"unauthorizedTables": [
"<string>"
],
"profiling": {
"profile_breakdown": {},
"compiled_sql": "<string>",
"original_sql": "<string>"
},
"truncated": true,
"needsConnection": {
"connectorId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"connectorName": "<string>",
"action": "connect_oauth"
}
}
}{
"status": "error",
"error": {
"message": "<string>",
"code": "<string>",
"details": {}
}
}Authorizations
Path Parameters
The project in the URL. The caller's project user is read from it.
Pattern:
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$POST /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/items/:itemId/run Parameter
Pattern:
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$POST /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/items/:itemId/run Parameter
Pattern:
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$POST /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/items/:itemId/run Parameter
Pattern:
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$Body
application/json
POST /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/items/:itemId/run Request body
Upsolve API key, generated under Account → Developer settings in the Upsolve Hub. Keys are user-scoped: pass organizationId alongside the key to select which org to act on.
Minimum string length:
1The ID of the organization. Required when using Supabase JWT authentication.
The ID of the connection a guest has access to
The viewer's UTC offset in hours. Used only when the canvas follows each viewer's own time zone; otherwise the canvas's time zone decides how dates are grouped and filtered.
Project user to run the query as; their properties drive the data model's row-level security. Required with an admin credential, ignored for a project-user token.
Published data model version to resolve fields and run queries against. Defaults to the published version.
Required range:
x <= 9007199254740991A saved canvas version to run the tile from, with that version's filters. Defaults to the live canvas.
Required range:
x <= 9007199254740991Session values for this canvas's filters, by filter id.
Show child attributes
Show child attributes
Filters to apply for this run only (not saved), expressed against catalog fields.
Show child attributes
Show child attributes
Was this page helpful?