Send a test report

Send a test report delivery

curl --request POST \
  --url https://api.example.com/report-previews/deliveries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Weekly cloud cost digest",
  "description": "Top movers across our AWS + GCP spend",
  "type": "PRIVATE",
  "context": {
    "metricId": "cost",
    "groupBy": "provider",
    "datePreset": "TRAILING_90_DAYS",
    "currency": "USD"
  },
  "scheduledPeriod": "WEEKLY",
  "scheduledWeekday": 1,
  "status": "ACTIVE",
  "widgets": [
    {
      "type": "TEXT",
      "contentMarkdown": "## Weekly summary"
    }
  ],
  "destinations": [
    {
      "destinationType": "SLACK",
      "destinationValues": [
        "C0123456789"
      ]
    },
    {
      "destinationType": "EMAIL",
      "destinationValues": [
        "finance@acme.com"
      ]
    }
  ]
}
'

import requests

url = "https://api.example.com/report-previews/deliveries"

payload = {
    "name": "Weekly cloud cost digest",
    "description": "Top movers across our AWS + GCP spend",
    "type": "PRIVATE",
    "context": {
        "metricId": "cost",
        "groupBy": "provider",
        "datePreset": "TRAILING_90_DAYS",
        "currency": "USD"
    },
    "scheduledPeriod": "WEEKLY",
    "scheduledWeekday": 1,
    "status": "ACTIVE",
    "widgets": [
        {
            "type": "TEXT",
            "contentMarkdown": "## Weekly summary"
        }
    ],
    "destinations": [
        {
            "destinationType": "SLACK",
            "destinationValues": ["C0123456789"]
        },
        {
            "destinationType": "EMAIL",
            "destinationValues": ["finance@acme.com"]
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Weekly cloud cost digest',
    description: 'Top movers across our AWS + GCP spend',
    type: 'PRIVATE',
    context: {
      metricId: 'cost',
      groupBy: 'provider',
      datePreset: 'TRAILING_90_DAYS',
      currency: 'USD'
    },
    scheduledPeriod: 'WEEKLY',
    scheduledWeekday: 1,
    status: 'ACTIVE',
    widgets: [{type: 'TEXT', contentMarkdown: '## Weekly summary'}],
    destinations: [
      {destinationType: 'SLACK', destinationValues: ['C0123456789']},
      {destinationType: 'EMAIL', destinationValues: ['finance@acme.com']}
    ]
  })
};

fetch('https://api.example.com/report-previews/deliveries', 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.example.com/report-previews/deliveries",
  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([
    'name' => 'Weekly cloud cost digest',
    'description' => 'Top movers across our AWS + GCP spend',
    'type' => 'PRIVATE',
    'context' => [
        'metricId' => 'cost',
        'groupBy' => 'provider',
        'datePreset' => 'TRAILING_90_DAYS',
        'currency' => 'USD'
    ],
    'scheduledPeriod' => 'WEEKLY',
    'scheduledWeekday' => 1,
    'status' => 'ACTIVE',
    'widgets' => [
        [
                'type' => 'TEXT',
                'contentMarkdown' => '## Weekly summary'
        ]
    ],
    'destinations' => [
        [
                'destinationType' => 'SLACK',
                'destinationValues' => [
                                'C0123456789'
                ]
        ],
        [
                'destinationType' => 'EMAIL',
                'destinationValues' => [
                                'finance@acme.com'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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 := "https://api.example.com/report-previews/deliveries"

	payload := strings.NewReader("{\n  \"name\": \"Weekly cloud cost digest\",\n  \"description\": \"Top movers across our AWS + GCP spend\",\n  \"type\": \"PRIVATE\",\n  \"context\": {\n    \"metricId\": \"cost\",\n    \"groupBy\": \"provider\",\n    \"datePreset\": \"TRAILING_90_DAYS\",\n    \"currency\": \"USD\"\n  },\n  \"scheduledPeriod\": \"WEEKLY\",\n  \"scheduledWeekday\": 1,\n  \"status\": \"ACTIVE\",\n  \"widgets\": [\n    {\n      \"type\": \"TEXT\",\n      \"contentMarkdown\": \"## Weekly summary\"\n    }\n  ],\n  \"destinations\": [\n    {\n      \"destinationType\": \"SLACK\",\n      \"destinationValues\": [\n        \"C0123456789\"\n      ]\n    },\n    {\n      \"destinationType\": \"EMAIL\",\n      \"destinationValues\": [\n        \"finance@acme.com\"\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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.example.com/report-previews/deliveries")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Weekly cloud cost digest\",\n  \"description\": \"Top movers across our AWS + GCP spend\",\n  \"type\": \"PRIVATE\",\n  \"context\": {\n    \"metricId\": \"cost\",\n    \"groupBy\": \"provider\",\n    \"datePreset\": \"TRAILING_90_DAYS\",\n    \"currency\": \"USD\"\n  },\n  \"scheduledPeriod\": \"WEEKLY\",\n  \"scheduledWeekday\": 1,\n  \"status\": \"ACTIVE\",\n  \"widgets\": [\n    {\n      \"type\": \"TEXT\",\n      \"contentMarkdown\": \"## Weekly summary\"\n    }\n  ],\n  \"destinations\": [\n    {\n      \"destinationType\": \"SLACK\",\n      \"destinationValues\": [\n        \"C0123456789\"\n      ]\n    },\n    {\n      \"destinationType\": \"EMAIL\",\n      \"destinationValues\": [\n        \"finance@acme.com\"\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/report-previews/deliveries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Weekly cloud cost digest\",\n  \"description\": \"Top movers across our AWS + GCP spend\",\n  \"type\": \"PRIVATE\",\n  \"context\": {\n    \"metricId\": \"cost\",\n    \"groupBy\": \"provider\",\n    \"datePreset\": \"TRAILING_90_DAYS\",\n    \"currency\": \"USD\"\n  },\n  \"scheduledPeriod\": \"WEEKLY\",\n  \"scheduledWeekday\": 1,\n  \"status\": \"ACTIVE\",\n  \"widgets\": [\n    {\n      \"type\": \"TEXT\",\n      \"contentMarkdown\": \"## Weekly summary\"\n    }\n  ],\n  \"destinations\": [\n    {\n      \"destinationType\": \"SLACK\",\n      \"destinationValues\": [\n        \"C0123456789\"\n      ]\n    },\n    {\n      \"destinationType\": \"EMAIL\",\n      \"destinationValues\": [\n        \"finance@acme.com\"\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "destinationIndex": 1,
      "ok": true,
      "errorMessage": "<string>"
    }
  ]
}

{
  "error": "VALIDATION_ERROR",
  "details": "<string>",
  "reason": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "FORBIDDEN"
}

{
  "error": "NOT_FOUND",
  "reason": "<string>"
}

POST

report-previews

deliveries

Send a test report delivery

curl --request POST \
  --url https://api.example.com/report-previews/deliveries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Weekly cloud cost digest",
  "description": "Top movers across our AWS + GCP spend",
  "type": "PRIVATE",
  "context": {
    "metricId": "cost",
    "groupBy": "provider",
    "datePreset": "TRAILING_90_DAYS",
    "currency": "USD"
  },
  "scheduledPeriod": "WEEKLY",
  "scheduledWeekday": 1,
  "status": "ACTIVE",
  "widgets": [
    {
      "type": "TEXT",
      "contentMarkdown": "## Weekly summary"
    }
  ],
  "destinations": [
    {
      "destinationType": "SLACK",
      "destinationValues": [
        "C0123456789"
      ]
    },
    {
      "destinationType": "EMAIL",
      "destinationValues": [
        "finance@acme.com"
      ]
    }
  ]
}
'

import requests

url = "https://api.example.com/report-previews/deliveries"

payload = {
    "name": "Weekly cloud cost digest",
    "description": "Top movers across our AWS + GCP spend",
    "type": "PRIVATE",
    "context": {
        "metricId": "cost",
        "groupBy": "provider",
        "datePreset": "TRAILING_90_DAYS",
        "currency": "USD"
    },
    "scheduledPeriod": "WEEKLY",
    "scheduledWeekday": 1,
    "status": "ACTIVE",
    "widgets": [
        {
            "type": "TEXT",
            "contentMarkdown": "## Weekly summary"
        }
    ],
    "destinations": [
        {
            "destinationType": "SLACK",
            "destinationValues": ["C0123456789"]
        },
        {
            "destinationType": "EMAIL",
            "destinationValues": ["finance@acme.com"]
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Weekly cloud cost digest',
    description: 'Top movers across our AWS + GCP spend',
    type: 'PRIVATE',
    context: {
      metricId: 'cost',
      groupBy: 'provider',
      datePreset: 'TRAILING_90_DAYS',
      currency: 'USD'
    },
    scheduledPeriod: 'WEEKLY',
    scheduledWeekday: 1,
    status: 'ACTIVE',
    widgets: [{type: 'TEXT', contentMarkdown: '## Weekly summary'}],
    destinations: [
      {destinationType: 'SLACK', destinationValues: ['C0123456789']},
      {destinationType: 'EMAIL', destinationValues: ['finance@acme.com']}
    ]
  })
};

fetch('https://api.example.com/report-previews/deliveries', 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.example.com/report-previews/deliveries",
  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([
    'name' => 'Weekly cloud cost digest',
    'description' => 'Top movers across our AWS + GCP spend',
    'type' => 'PRIVATE',
    'context' => [
        'metricId' => 'cost',
        'groupBy' => 'provider',
        'datePreset' => 'TRAILING_90_DAYS',
        'currency' => 'USD'
    ],
    'scheduledPeriod' => 'WEEKLY',
    'scheduledWeekday' => 1,
    'status' => 'ACTIVE',
    'widgets' => [
        [
                'type' => 'TEXT',
                'contentMarkdown' => '## Weekly summary'
        ]
    ],
    'destinations' => [
        [
                'destinationType' => 'SLACK',
                'destinationValues' => [
                                'C0123456789'
                ]
        ],
        [
                'destinationType' => 'EMAIL',
                'destinationValues' => [
                                'finance@acme.com'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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 := "https://api.example.com/report-previews/deliveries"

	payload := strings.NewReader("{\n  \"name\": \"Weekly cloud cost digest\",\n  \"description\": \"Top movers across our AWS + GCP spend\",\n  \"type\": \"PRIVATE\",\n  \"context\": {\n    \"metricId\": \"cost\",\n    \"groupBy\": \"provider\",\n    \"datePreset\": \"TRAILING_90_DAYS\",\n    \"currency\": \"USD\"\n  },\n  \"scheduledPeriod\": \"WEEKLY\",\n  \"scheduledWeekday\": 1,\n  \"status\": \"ACTIVE\",\n  \"widgets\": [\n    {\n      \"type\": \"TEXT\",\n      \"contentMarkdown\": \"## Weekly summary\"\n    }\n  ],\n  \"destinations\": [\n    {\n      \"destinationType\": \"SLACK\",\n      \"destinationValues\": [\n        \"C0123456789\"\n      ]\n    },\n    {\n      \"destinationType\": \"EMAIL\",\n      \"destinationValues\": [\n        \"finance@acme.com\"\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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.example.com/report-previews/deliveries")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Weekly cloud cost digest\",\n  \"description\": \"Top movers across our AWS + GCP spend\",\n  \"type\": \"PRIVATE\",\n  \"context\": {\n    \"metricId\": \"cost\",\n    \"groupBy\": \"provider\",\n    \"datePreset\": \"TRAILING_90_DAYS\",\n    \"currency\": \"USD\"\n  },\n  \"scheduledPeriod\": \"WEEKLY\",\n  \"scheduledWeekday\": 1,\n  \"status\": \"ACTIVE\",\n  \"widgets\": [\n    {\n      \"type\": \"TEXT\",\n      \"contentMarkdown\": \"## Weekly summary\"\n    }\n  ],\n  \"destinations\": [\n    {\n      \"destinationType\": \"SLACK\",\n      \"destinationValues\": [\n        \"C0123456789\"\n      ]\n    },\n    {\n      \"destinationType\": \"EMAIL\",\n      \"destinationValues\": [\n        \"finance@acme.com\"\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/report-previews/deliveries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Weekly cloud cost digest\",\n  \"description\": \"Top movers across our AWS + GCP spend\",\n  \"type\": \"PRIVATE\",\n  \"context\": {\n    \"metricId\": \"cost\",\n    \"groupBy\": \"provider\",\n    \"datePreset\": \"TRAILING_90_DAYS\",\n    \"currency\": \"USD\"\n  },\n  \"scheduledPeriod\": \"WEEKLY\",\n  \"scheduledWeekday\": 1,\n  \"status\": \"ACTIVE\",\n  \"widgets\": [\n    {\n      \"type\": \"TEXT\",\n      \"contentMarkdown\": \"## Weekly summary\"\n    }\n  ],\n  \"destinations\": [\n    {\n      \"destinationType\": \"SLACK\",\n      \"destinationValues\": [\n        \"C0123456789\"\n      ]\n    },\n    {\n      \"destinationType\": \"EMAIL\",\n      \"destinationValues\": [\n        \"finance@acme.com\"\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "destinationIndex": 1,
      "ok": true,
      "errorMessage": "<string>"
    }
  ]
}

{
  "error": "VALIDATION_ERROR",
  "details": "<string>",
  "reason": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "FORBIDDEN"
}

{
  "error": "NOT_FOUND",
  "reason": "<string>"
}

Authorizations

Authorization

string

header

required

Send Authorization: Bearer <credential> using either a Clerk session JWT or a Clerk API key (ak_*). API keys may identify a user (user_*) or organization (org_*) principal and are generated in the Clerk Dashboard under API keys.

Body

application/json

name

string

required

Report name. May be empty or whitespace — the server then generates one from the report's content.

scheduledPeriod

enum<string> | null

required

Delivery cadence, or null for an on-demand (one-time) report that only runs when triggered.

Available options:

DAILY,

WEEKDAYS,

WEEKLY,

MONTHLY,

null

destinations

object[]

required

Delivery targets. At least one is required. Each report is fanned out to every destination on every run.

Minimum array length: 1

Show child attributes

description

string

default:""

Optional longer description (default empty).

type

enum<string>

default:PRIVATE

Deprecated. On create, PUBLIC still seeds an organization Editor grant (and PRIVATE does not). On update it is ignored — grant Reader or Editor via PUT /access/report/:id/grants instead. TEMPLATE is dashboard-only.

Available options:

PRIVATE,

PUBLIC

tagIds

string[]

Existing org tag ids to assign. Omit for untagged.

teamId

string | null

Deprecated. On create, a non-null teamId still seeds a team Editor grant. On update it is ignored — grant a team Reader or Editor via PUT /access/report/:id/grants instead.

scopeId

string | null

context

object

Report-wide defaults (metric, group-by, date range, filters, currency) that widgets and destinations inherit unless they override them.

Show child attributes

scheduledWeekday

number

Day of week for WEEKLY reports: 0 = Sunday … 6 = Saturday. Required when scheduledPeriod is WEEKLY; ignored for every other cadence.

scheduledFirstRunAt

string<date-time> | null

First send date (UTC). The time of day is ignored: the report is due for the whole UTC day, as soon as the org is ready. Ignored once the report has run at least once.

status

enum<string>

Available options:

ACTIVE,

INACTIVE

widgets

object[]

Ordered widgets that make up the report body. Each widget's type selects its shape (see ReportWidgetParameters).

One report widget. The type field selects the shape: TOP_FLOP | GRAPH_SNAPSHOT | DASHBOARD_PDF | DIGEST | TEXT. All fields other than type depend on the chosen type.

Option 1
Option 2
Option 3
Option 4
Option 5

Show child attributes

reportId

string<cuid>

Response

Per-destination send results

results

object[]

required

Show child attributes

Last modified on July 20, 2026

Getting started

Query Costs API

Reports API

Report Previews

Enrichments API

Alerts V2

Dimensions

Metrics

Enrichments

Dashboards

Reports

Query Costs

Events

Admin

Admin Billing Datasources

Admin Teams

Custom Metrics

Access

Authorizations

Body

Response