Skip to main content
POST
/
api
/
report_queries
Create a report query
curl --request POST \
  --url https://clarus-api.com/api/report_queries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Clarus-Subdomain: <api-key>' \
  --data '
{
  "data": {
    "type": "report_queries",
    "attributes": {
      "name": "Count of Tasks Left To Do",
      "description": "Count of Tasks Left To Do by Task Type",
      "graphql": "query getTasksToDo($warehouse_id: ID, $account_id: ID, $created_at_from: Chronic, $created_at_to: Chronic) { tasks { aggregation(group_by: [task_type_id], statuses: [\"AVAILABLE\", \"ALLOCATED\"], warehouse_id: $warehouse_id, account_id: $account_id, created_from: $created_at_from, created_to: $created_at_to, limit: 9999999, order: \"total_records DESC\") { task_type { code } total_records } } }",
      "parameters": [
        {
          "name": "warehouse_id",
          "type": "Integer"
        },
        {
          "name": "account_id",
          "type": "Integer"
        },
        {
          "name": "created_at_from",
          "type": "Date"
        },
        {
          "name": "created_at_to",
          "type": "Date"
        }
      ]
    }
  }
}
'
{
  "data": {
    "id": 123,
    "type": "report_queries",
    "attributes": {
      "name": "Count of Tasks Left To Do",
      "description": "Count of Tasks Left To Do by Task Type",
      "graphql": "query getTasksToDo($warehouse_id: ID, $account_id: ID, $created_at_from: Chronic, $created_at_to: Chronic) { tasks { aggregation(group_by: [task_type_id], statuses: [\"AVAILABLE\", \"ALLOCATED\"], warehouse_id: $warehouse_id, account_id: $account_id, created_from: $created_at_from, created_to: $created_at_to, limit: 9999999, order: \"total_records DESC\") { task_type { code } total_records } } }",
      "parameters": [
        {
          "name": "warehouse_id",
          "type": "Integer"
        },
        {
          "name": "account_id",
          "type": "Integer"
        },
        {
          "name": "created_at_from",
          "type": "Date"
        },
        {
          "name": "created_at_to",
          "type": "Date"
        }
      ]
    }
  }
}

​
Request Structure

{
  "data": {
    "type": "report_queries",
    "attributes": {
      "name": "Count of Tasks Left To Do",
      "description": "Count of Tasks Left To Do by Task Type",
      "graphql": "query getTasksToDo($warehouse_id: ID, $account_id: ID, $created_at_from: Chronic, $created_at_to: Chronic) { tasks { aggregation(group_by: [task_type_id], statuses: [\"AVAILABLE\", \"ALLOCATED\"], warehouse_id: $warehouse_id, account_id: $account_id, created_from: $created_at_from, created_to: $created_at_to, limit: 9999999, order: \"total_records DESC\") { task_type { code } total_records } } }",
      "parameters": [
        { "name": "warehouse_id", "type": "Integer" },
        { "name": "account_id", "type": "Integer" },
        { "name": "created_at_from", "type": "Date" },
        { "name": "created_at_to", "type": "Date" }
      ]
    }
  }
}

​
Key Fields

FieldRequiredDescription
nameYesReport name for identification
descriptionNoDescription of what the report shows
graphqlYesNamed GraphQL query with typed parameters (never anonymous)
parametersNoArray of parameter definitions matching query variables

​
GraphQL Query Rules

  • Must be a named query (e.g., query getTasksToDo(...)) — never anonymous
  • Use $variable syntax for parameters with GraphQL types (ID, Chronic, String)
  • Common query patterns: aggregation(...) for grouped/summarized data, all(...) { edges { node { ... } } } for paginated lists

​
Parameter Types

TypeGraphQL TypeDescription
IntegerIDInteger ID value
DateChronicDate/time parsed with natural language (e.g., ‘start of today’)
StringStringText value

Authorizations

​
Authorization
string
header
required

OAuth 2.0 authentication. Use the client credentials or authorization code flow to obtain an access token.

​
X-Clarus-Subdomain
string
header
required

The subdomain/tenant name identifying which tenant's data to access. Required for all API requests.

Body

application/json
​
data
object
required

Response

Report query created successfully

​
data
object