Skip to main content
POST
/
data
/
projects
/
{projectId}
/
queries
curl --request POST \
  --url https://partner.peaka.studio/api/v1/data/projects/{projectId}/queries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "displayName": "sampleQuery",
  "inputQuery": "SELECT * from \"mycatalog\".payment.customers"
}
'
{
  "id": "<string>",
  "displayName": "<string>",
  "name": "<string>",
  "inputQuery": "<string>",
  "schedule": {
    "type": "cron",
    "cronExpression": "0 0 * * *",
    "timezone": "UTC"
  },
  "path": "<string>",
  "folderId": "<string>"
}
Looking to materialize an existing query? See How to Materialize a Query with the Peaka API for the full workflow — creating a MATERIALIZED query from inputQueryRefId, scheduling refreshes, and querying the result.

Authorizations

​
Authorization
string
header
required

Use the Authorization header with the value 'Bearer ' to authenticate. Partner API Keys have full access; Project API Keys are limited to their project scope. Learn more: https://docs.peaka.com/api-reference/authentication

Path Parameters

​
projectId
string
required

ID of the Project

Query Parameters

​
checkSchemaExists
boolean
default:true

Body

application/json

Query Request

​
displayName
string

The display name of the query.

Example:

"sampleQuery"

​
inputQuery
string | null

The SQL query. Required unless inputQueryRefId is provided.

​
queryType
enum<string>
default:PLAIN

The type of the query. Defaults to PLAIN.

Available options:
PLAIN,
MATERIALIZED
​
schedule
object | null

Schedule configuration of a materialized query. Provide EITHER an interval schedule (type=interval with repeatDuration) OR a cron schedule (type=cron with cronExpression and optional timezone). Use type=none for no schedule. The fields that do not apply to the chosen type are omitted.

Example:
{
  "type": "cron",
  "cronExpression": "0 0 * * *",
  "timezone": "UTC"
}
​
inputQueryRefId
string | null

The id of an existing query to materialize. Valid only if the query type is MATERIALIZED. When set, the materialized query is built from the referenced query's SQL and inputQuery is not required. The reference is resolved when the request is processed: a snapshot of the referenced query's SQL is stored as this query's inputQuery. The reference id itself is not persisted and is not returned in responses; later changes to the referenced query do not propagate. Send the reference again on an update to re-resolve from the source.

Example:

"709922802836177297"

​
path
string | null

The folder path to place this query in. Intermediate folders are created automatically. If omitted, the query is placed at the root level.

Example:

"/reports/monthly"

Response

200 - application/json

Query created

A saved query belonging to a project.

​
id
string

The ID of the query.

​
displayName
string

The display name of the query.

​
name
string

The name of the query used in SQL, e.g. SELECT * FROM "peaka"."query"."". For a MATERIALIZED query the materialized result is queryable as "peaka"."mtquery"."".

​
inputQuery
string

The SQL query. For a materialized query created from an existing query (via inputQueryRefId), this holds the snapshot of the source query's SQL resolved when the query was created or last updated with the reference.

​
queryType
enum<string>

The type of the query.

Available options:
PLAIN,
MATERIALIZED
​
schedule
object | null

Schedule configuration of a materialized query. Provide EITHER an interval schedule (type=interval with repeatDuration) OR a cron schedule (type=cron with cronExpression and optional timezone). Use type=none for no schedule. The fields that do not apply to the chosen type are omitted.

Example:
{
  "type": "cron",
  "cronExpression": "0 0 * * *",
  "timezone": "UTC"
}
​
path
string | null

The folder path of the query (e.g. "/analytics/dashboards"). Null if not in any folder.

​
folderId
string | null

The ID of the folder containing this query. Null if not in any folder.