The Insights API

{  "name": "My Report",

  "show_in_ui": false,

  "form": {

    "deployment_id": 5716,

    "report_type": "compute_waterfall_summary",

    "start_date": "2024-01-01",

    "end_date": "2024-03-31"

  }

}

# Recast Insights API — R Usage Example
​
#

# Workflow: Create report → Poll → List downloads → Download CSVs

#

# Prerequisites:

#   install.packages(c("httr2", "jsonlite"))

#   Add to .Renviron: API_PAT=gr_your_token_here

library(httr2)

library(jsonlite)

BASE_URL    <- "https://api.getrecast.com"

CLIENT_SLUG <- "democlient"  # Update to your client slug

PAT         <- Sys.getenv("API_PAT")

parse <- \(resp) resp |> resp_body_string() |> fromJSON(simplifyVector = FALSE)

check <- function(resp, expected = 200) {

  if (resp_status(resp) != expected) {

    stop(sprintf("HTTP %d: %s", resp_status(resp), resp_body_string(resp)))

  }

  resp

}

report_request <- function(...) {

  request(BASE_URL) |>

    req_url_path_append("v1", "clients", CLIENT_SLUG, "reports", ...) |>

    req_auth_bearer_token(PAT) |>

    req_headers(Accept = "application/json") |>

    req_error(is_error = \(resp) FALSE)

}

# Step 1: Create a report

# report_type goes inside form, not at the top level

resp <- report_request() |>

  req_method("POST") |>

  req_headers(`Content-Type` = "application/json") |>

  req_body_json(list(

    name       = paste("Channel Attribution -", Sys.Date()),

    show_in_ui = FALSE,

    form       = list(

      deployment_id = 5716,       # Update to your deployment ID

      report_type   = "compute_waterfall_summary",

      start_date    = "2024-01-01",

      end_date      = "2024-03-31"

    )

  ), auto_unbox = TRUE) |>

  req_perform() |>

  check(expected = 201)

report_id <- parse(resp)$id

cat(sprintf("Created report %d\n", report_id))

# Step 2: Poll until complete (typically 1–5 minutes)

repeat {

  result <- report_request(report_id) |> req_perform() |> check() |> parse()

  cat(sprintf("Status: %s\n", result$status))

  if (!result$status %in% c("ready", "processing")) break

  Sys.sleep(30)

}

if (result$status != "success") {

  stop(sprintf("Report ended with status: %s", result$status))

}

# Step 3: Download all available CSVs

downloads <- result$results$downloads

cat(sprintf("Downloading %d files...\n", length(downloads)))

for (dl in downloads) {

  csv_resp <- report_request(report_id, "downloads", dl$key) |>

    req_perform() |>

    check()

  df <- read.csv(text = resp_body_string(csv_resp), check.names = FALSE)

  write.csv(df, file = paste0(dl$key, ".csv"), row.names = FALSE)

  cat(sprintf("  Saved %s.csv (%d rows)\n", dl$key, nrow(df)))

}

#

# Workflow: Create report → Poll → List downloads → Download CSVs

#

# Prerequisites:

#   pip install requests pandas

#   Set environment variable: export API_PAT=gr_your_token_here

import os

import time

import io

import requests

import pandas as pd

from datetime import date

BASE_URL    = "https://api.getrecast.com"

CLIENT_SLUG = "democlient"  # Update to your client slug

PAT         = os.environ["API_PAT"]

BASE_PATH = f"{BASE_URL}/v1/clients/{CLIENT_SLUG}/reports"

HEADERS   = {"Authorization": f"Bearer {PAT}", "Accept": "application/json"}

def check(resp, expected=200):

    if resp.status_code != expected:

        raise Exception(f"HTTP {resp.status_code}: {resp.text}")

    return resp

# Step 1: Create a report

# report_type goes inside form, not at the top level

resp = check(requests.post(

    BASE_PATH,

    headers={**HEADERS, "Content-Type": "application/json"},

    json={

        "name": f"Channel Attribution - {date.today()}",

        "show_in_ui": False,

        "form": {

            "deployment_id": 5716,         # Update to your deployment ID

            "report_type": "compute_waterfall_summary",

            "start_date": "2024-01-01",

            "end_date": "2024-03-31",

        },

    },

), expected=201)

report_id = resp.json()["id"]

print(f"Created report {report_id}")

# Step 2: Poll until complete (typically 1–5 minutes)

while True:

    result = check(requests.get(f"{BASE_PATH}/{report_id}", headers=HEADERS)).json()

    print(f"Status: {result['status']}")

    if result["status"] not in ("ready", "processing"):

        break

    time.sleep(30)

if result["status"] != "success":

    raise Exception(f"Report ended with status: {result['status']}")

# Step 3: Download all available CSVs

downloads = result["results"]["downloads"]

print(f"Downloading {len(downloads)} files...")

for dl in downloads:

    csv_resp = check(requests.get(

        f"{BASE_PATH}/{report_id}/downloads/{dl['key']}",

        headers=HEADERS,

    ))

    df = pd.read_csv(io.StringIO(csv_resp.text))

    df.to_csv(f"{dl['key']}.csv", index=False)

    print(f"  Saved {dl['key']}.csv ({len(df)} rows)")