Create Ask Job
curl --request POST \
--url http://localhost:8080/v1/knowledge/ask/jobs \
--header 'Content-Type: application/json' \
--data '
{
"query": "What are our top blockers for Q1?",
"timezone": "America/New_York",
"metadata": {
"env": "staging"
},
"filter": {
"must": [
{
"key": "source",
"match": {
"any": [
"email",
"calendar_event"
]
}
},
{
"key": "timestamp",
"range": {
"gte": "2026-01-01",
"lte": "2026-03-31"
}
}
],
"must_not": [
{
"key": "sensitivity",
"match": {
"value": "restricted"
}
}
],
"should": [
{
"key": "connection",
"match": {
"value": "gmail:acme"
}
},
{
"key": "connection",
"match": {
"value": "slack:acme"
}
}
]
}
}
'import requests
url = "http://localhost:8080/v1/knowledge/ask/jobs"
payload = {
"query": "What are our top blockers for Q1?",
"timezone": "America/New_York",
"metadata": { "env": "staging" },
"filter": {
"must": [
{
"key": "source",
"match": { "any": ["email", "calendar_event"] }
},
{
"key": "timestamp",
"range": {
"gte": "2026-01-01",
"lte": "2026-03-31"
}
}
],
"must_not": [
{
"key": "sensitivity",
"match": { "value": "restricted" }
}
],
"should": [
{
"key": "connection",
"match": { "value": "gmail:acme" }
},
{
"key": "connection",
"match": { "value": "slack:acme" }
}
]
}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'What are our top blockers for Q1?',
timezone: 'America/New_York',
metadata: {env: 'staging'},
filter: {
must: [
{key: 'source', match: {any: ['email', 'calendar_event']}},
{key: 'timestamp', range: {gte: '2026-01-01', lte: '2026-03-31'}}
],
must_not: [{key: 'sensitivity', match: {value: 'restricted'}}],
should: [
{key: 'connection', match: {value: 'gmail:acme'}},
{key: 'connection', match: {value: 'slack:acme'}}
]
}
})
};
fetch('http://localhost:8080/v1/knowledge/ask/jobs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "8080",
CURLOPT_URL => "http://localhost:8080/v1/knowledge/ask/jobs",
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([
'query' => 'What are our top blockers for Q1?',
'timezone' => 'America/New_York',
'metadata' => [
'env' => 'staging'
],
'filter' => [
'must' => [
[
'key' => 'source',
'match' => [
'any' => [
'email',
'calendar_event'
]
]
],
[
'key' => 'timestamp',
'range' => [
'gte' => '2026-01-01',
'lte' => '2026-03-31'
]
]
],
'must_not' => [
[
'key' => 'sensitivity',
'match' => [
'value' => 'restricted'
]
]
],
'should' => [
[
'key' => 'connection',
'match' => [
'value' => 'gmail:acme'
]
],
[
'key' => 'connection',
'match' => [
'value' => 'slack:acme'
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$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 := "http://localhost:8080/v1/knowledge/ask/jobs"
payload := strings.NewReader("{\n \"query\": \"What are our top blockers for Q1?\",\n \"timezone\": \"America/New_York\",\n \"metadata\": {\n \"env\": \"staging\"\n },\n \"filter\": {\n \"must\": [\n {\n \"key\": \"source\",\n \"match\": {\n \"any\": [\n \"email\",\n \"calendar_event\"\n ]\n }\n },\n {\n \"key\": \"timestamp\",\n \"range\": {\n \"gte\": \"2026-01-01\",\n \"lte\": \"2026-03-31\"\n }\n }\n ],\n \"must_not\": [\n {\n \"key\": \"sensitivity\",\n \"match\": {\n \"value\": \"restricted\"\n }\n }\n ],\n \"should\": [\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"gmail:acme\"\n }\n },\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"slack:acme\"\n }\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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("http://localhost:8080/v1/knowledge/ask/jobs")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"What are our top blockers for Q1?\",\n \"timezone\": \"America/New_York\",\n \"metadata\": {\n \"env\": \"staging\"\n },\n \"filter\": {\n \"must\": [\n {\n \"key\": \"source\",\n \"match\": {\n \"any\": [\n \"email\",\n \"calendar_event\"\n ]\n }\n },\n {\n \"key\": \"timestamp\",\n \"range\": {\n \"gte\": \"2026-01-01\",\n \"lte\": \"2026-03-31\"\n }\n }\n ],\n \"must_not\": [\n {\n \"key\": \"sensitivity\",\n \"match\": {\n \"value\": \"restricted\"\n }\n }\n ],\n \"should\": [\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"gmail:acme\"\n }\n },\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"slack:acme\"\n }\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8080/v1/knowledge/ask/jobs")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"What are our top blockers for Q1?\",\n \"timezone\": \"America/New_York\",\n \"metadata\": {\n \"env\": \"staging\"\n },\n \"filter\": {\n \"must\": [\n {\n \"key\": \"source\",\n \"match\": {\n \"any\": [\n \"email\",\n \"calendar_event\"\n ]\n }\n },\n {\n \"key\": \"timestamp\",\n \"range\": {\n \"gte\": \"2026-01-01\",\n \"lte\": \"2026-03-31\"\n }\n }\n ],\n \"must_not\": [\n {\n \"key\": \"sensitivity\",\n \"match\": {\n \"value\": \"restricted\"\n }\n }\n ],\n \"should\": [\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"gmail:acme\"\n }\n },\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"slack:acme\"\n }\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{}{
"error_code": "authentication_error",
"message": "Invalid or missing credentials.",
"details": {}
}{
"error_code": "quota_exceeded",
"message": "Ask refused: this workspace has used all the asks its plan includes.",
"details": {}
}{
"error_code": "permission_denied",
"message": "You do not have permission to perform this action.",
"details": {}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"type": "<string>",
"detail": "<string>",
"endpoint": "<string>",
"tier": "<string>",
"limit": 123,
"remaining": 123,
"window_seconds": 123,
"retry_after": 123,
"title": "Too Many Requests",
"status": 429,
"error_code": "rate_limit_exceeded",
"instance": "<string>"
}{
"error_code": "internal_server_error",
"message": "An unexpected error occurred.",
"details": {}
}{
"error_code": "service_unavailable",
"message": "The service is currently experiencing issues. Please try again later.",
"details": {}
}Knowledge
Create Ask Job
Ask a question asynchronously: returns a job id immediately; poll
GET /knowledge/ask/jobs/ until status leaves “running”. Same
grounding and citations as /knowledge/ask, without the long-poll timeout —
use for deep or broad questions that may exceed the sync window.
POST
/
v1
/
knowledge
/
ask
/
jobs
Create Ask Job
curl --request POST \
--url http://localhost:8080/v1/knowledge/ask/jobs \
--header 'Content-Type: application/json' \
--data '
{
"query": "What are our top blockers for Q1?",
"timezone": "America/New_York",
"metadata": {
"env": "staging"
},
"filter": {
"must": [
{
"key": "source",
"match": {
"any": [
"email",
"calendar_event"
]
}
},
{
"key": "timestamp",
"range": {
"gte": "2026-01-01",
"lte": "2026-03-31"
}
}
],
"must_not": [
{
"key": "sensitivity",
"match": {
"value": "restricted"
}
}
],
"should": [
{
"key": "connection",
"match": {
"value": "gmail:acme"
}
},
{
"key": "connection",
"match": {
"value": "slack:acme"
}
}
]
}
}
'import requests
url = "http://localhost:8080/v1/knowledge/ask/jobs"
payload = {
"query": "What are our top blockers for Q1?",
"timezone": "America/New_York",
"metadata": { "env": "staging" },
"filter": {
"must": [
{
"key": "source",
"match": { "any": ["email", "calendar_event"] }
},
{
"key": "timestamp",
"range": {
"gte": "2026-01-01",
"lte": "2026-03-31"
}
}
],
"must_not": [
{
"key": "sensitivity",
"match": { "value": "restricted" }
}
],
"should": [
{
"key": "connection",
"match": { "value": "gmail:acme" }
},
{
"key": "connection",
"match": { "value": "slack:acme" }
}
]
}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'What are our top blockers for Q1?',
timezone: 'America/New_York',
metadata: {env: 'staging'},
filter: {
must: [
{key: 'source', match: {any: ['email', 'calendar_event']}},
{key: 'timestamp', range: {gte: '2026-01-01', lte: '2026-03-31'}}
],
must_not: [{key: 'sensitivity', match: {value: 'restricted'}}],
should: [
{key: 'connection', match: {value: 'gmail:acme'}},
{key: 'connection', match: {value: 'slack:acme'}}
]
}
})
};
fetch('http://localhost:8080/v1/knowledge/ask/jobs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "8080",
CURLOPT_URL => "http://localhost:8080/v1/knowledge/ask/jobs",
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([
'query' => 'What are our top blockers for Q1?',
'timezone' => 'America/New_York',
'metadata' => [
'env' => 'staging'
],
'filter' => [
'must' => [
[
'key' => 'source',
'match' => [
'any' => [
'email',
'calendar_event'
]
]
],
[
'key' => 'timestamp',
'range' => [
'gte' => '2026-01-01',
'lte' => '2026-03-31'
]
]
],
'must_not' => [
[
'key' => 'sensitivity',
'match' => [
'value' => 'restricted'
]
]
],
'should' => [
[
'key' => 'connection',
'match' => [
'value' => 'gmail:acme'
]
],
[
'key' => 'connection',
'match' => [
'value' => 'slack:acme'
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$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 := "http://localhost:8080/v1/knowledge/ask/jobs"
payload := strings.NewReader("{\n \"query\": \"What are our top blockers for Q1?\",\n \"timezone\": \"America/New_York\",\n \"metadata\": {\n \"env\": \"staging\"\n },\n \"filter\": {\n \"must\": [\n {\n \"key\": \"source\",\n \"match\": {\n \"any\": [\n \"email\",\n \"calendar_event\"\n ]\n }\n },\n {\n \"key\": \"timestamp\",\n \"range\": {\n \"gte\": \"2026-01-01\",\n \"lte\": \"2026-03-31\"\n }\n }\n ],\n \"must_not\": [\n {\n \"key\": \"sensitivity\",\n \"match\": {\n \"value\": \"restricted\"\n }\n }\n ],\n \"should\": [\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"gmail:acme\"\n }\n },\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"slack:acme\"\n }\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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("http://localhost:8080/v1/knowledge/ask/jobs")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"What are our top blockers for Q1?\",\n \"timezone\": \"America/New_York\",\n \"metadata\": {\n \"env\": \"staging\"\n },\n \"filter\": {\n \"must\": [\n {\n \"key\": \"source\",\n \"match\": {\n \"any\": [\n \"email\",\n \"calendar_event\"\n ]\n }\n },\n {\n \"key\": \"timestamp\",\n \"range\": {\n \"gte\": \"2026-01-01\",\n \"lte\": \"2026-03-31\"\n }\n }\n ],\n \"must_not\": [\n {\n \"key\": \"sensitivity\",\n \"match\": {\n \"value\": \"restricted\"\n }\n }\n ],\n \"should\": [\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"gmail:acme\"\n }\n },\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"slack:acme\"\n }\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8080/v1/knowledge/ask/jobs")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"What are our top blockers for Q1?\",\n \"timezone\": \"America/New_York\",\n \"metadata\": {\n \"env\": \"staging\"\n },\n \"filter\": {\n \"must\": [\n {\n \"key\": \"source\",\n \"match\": {\n \"any\": [\n \"email\",\n \"calendar_event\"\n ]\n }\n },\n {\n \"key\": \"timestamp\",\n \"range\": {\n \"gte\": \"2026-01-01\",\n \"lte\": \"2026-03-31\"\n }\n }\n ],\n \"must_not\": [\n {\n \"key\": \"sensitivity\",\n \"match\": {\n \"value\": \"restricted\"\n }\n }\n ],\n \"should\": [\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"gmail:acme\"\n }\n },\n {\n \"key\": \"connection\",\n \"match\": {\n \"value\": \"slack:acme\"\n }\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{}{
"error_code": "authentication_error",
"message": "Invalid or missing credentials.",
"details": {}
}{
"error_code": "quota_exceeded",
"message": "Ask refused: this workspace has used all the asks its plan includes.",
"details": {}
}{
"error_code": "permission_denied",
"message": "You do not have permission to perform this action.",
"details": {}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"type": "<string>",
"detail": "<string>",
"endpoint": "<string>",
"tier": "<string>",
"limit": 123,
"remaining": 123,
"window_seconds": 123,
"retry_after": 123,
"title": "Too Many Requests",
"status": 429,
"error_code": "rate_limit_exceeded",
"instance": "<string>"
}{
"error_code": "internal_server_error",
"message": "An unexpected error occurred.",
"details": {}
}{
"error_code": "service_unavailable",
"message": "The service is currently experiencing issues. Please try again later.",
"details": {}
}Body
application/json
Required string length:
1 - 16000Example:
"What are our top blockers for Q1?"
IANA timezone identifier (e.g. "America/New_York") for resolving relative time references like "today" or "last week". Unknown identifiers are rejected. Defaults to America/New_York when omitted.
Example:
"America/New_York"
Restrict the evidence the model can ground its answer in to rows whose metadata contains ALL the given key/value pairs. Shorthand for a filter whose must lists each pair; combines with filter when both are set. Max 20 keys; string values only.
Show child attributes
Show child attributes
Example:
{ "env": "staging" }
Boolean scope over items. Conditions test a field: source (source type such as email, slack_message, calendar_event, or a custom kind), connection (the connected account or custom connector, such as gmail:acme), timestamp (a date range), or any metadata tag you set at ingest on custom-connector items. must is AND, should is OR, must_not is NOT; nest a filter condition to group. Max depth 3. Example: emails and meetings from Q1 2026 in either of two accounts, excluding items tagged restricted. Any scope switches the answer to evidence retrieval only, so the model searches and reads matching records instead of querying your knowledge graph.
Show child attributes
Show child attributes
Example:
{ "must": [ { "key": "source", "match": { "any": ["email", "calendar_event"] } }, { "key": "timestamp", "range": { "gte": "2026-01-01", "lte": "2026-03-31" } } ], "must_not": [ { "key": "sensitivity", "match": { "value": "restricted" } } ], "should": [ { "key": "connection", "match": { "value": "gmail:acme" } }, { "key": "connection", "match": { "value": "slack:acme" } } ] }
Response
Successful Response
The response is of type Response Create Ask Job · object.
Was this page helpful?