Exporting to Snowflake

Overview

Roark analyzes every call and produces structured metric values (frustration, sentiment, task completion, latency, custom metrics, and more). A common next step is to land that analysis in your own data warehouse so you can join it against your operational data, for example correlating call frustration with downstream business outcomes. This guide covers the recommended pattern for syncing Roark analysis into Snowflake using the tools available today. The same approach works for BigQuery, Redshift, or Databricks: only the load step changes.

Want a fully managed connector or a scheduled file drop into your own bucket? See Deeper integrations at the bottom of this page and reach out. We are actively expanding warehouse-export options.

The recommended pattern

The pattern is event-driven pull: Roark notifies you when a call finishes analysis, you pull the results from the API, land the raw JSON in cloud storage, and load it into Snowflake.

Roark webhook  ──▶  your handler  ──▶  fetch metrics/transcript  ──▶  S3 (raw JSON)  ──▶  Snowpipe  ──▶  Snowflake

Roark webhooks are a notification, not the payload. When a call is analyzed you receive the callId, not the metric values themselves, so your handler makes one follow-up API call to fetch the analysis. This keeps payloads small and lets you pull exactly the fields you need.

Create a read-only API key

Generate a key scoped to the project you want to export. Read endpoints require the call:read, metric:read, and transcript:read permissions. See API Keys.

Subscribe to analysis webhooks

Add a webhook endpoint and subscribe to call.analysis.completed. See Webhooks.

Fetch analysis on each event

In your handler, call the metrics (and optionally transcript) endpoints for the callId you received.

Land the raw JSON in cloud storage

Write each call’s payload to S3 (or GCS / Azure Blob). Store it as raw JSON so schema changes never break ingestion.

Load into Snowflake

Point Snowpipe at the bucket to auto-ingest, then flatten into modeled tables.

What you can export

All data is served from the Customer API at https://api.roark.ai/v1 and is scoped to the project your API key belongs to.

Data	Endpoint	Permission
List of calls (paginated)	`GET /v1/call`	`call:read`
Single call detail	`GET /v1/call/{callId}`	`call:read`
Metric values for a call	`GET /v1/call/{callId}/metrics`	`metric:read`
Transcript for a call	`GET /v1/call/{callId}/transcript`	`transcript:read`
Metric values for a whole collection job	`GET /v1/metric/collection-jobs/{jobId}/metric-values`	`metric:read`
Metric definitions (catalog)	`GET /v1/metric/definitions`	`metric:read`

Chats have the identical set of endpoints under /v1/chat.

Every call carries an externalId (your own correlation ID, set when the call is ingested) and a properties map of custom key-values. These are your join keys back to operational data in your warehouse.

Approach A: Event-driven (recommended for ongoing sync)

Best for keeping the warehouse continuously fresh with low latency.

@app.route('/webhooks/roark', methods=['POST'])
def handle_webhook():
    payload = request.json
    if payload['event'] == 'call.analysis.completed':
        call_id = payload['data']['callId']

        # Pull the analysis Roark just finished
        call = get(f'/v1/call/{call_id}')
        metrics = get(f'/v1/call/{call_id}/metrics')

        # Land raw JSON in S3, keyed by call id
        s3.put_object(
            Bucket='my-roark-export',
            Key=f'calls/{call_id}.json',
            Body=json.dumps({'call': call, 'metrics': metrics}),
        )
    return '', 200


def get(path):
    r = requests.get(
        f'https://api.roark.ai{path}',
        headers={'Authorization': f'Bearer {ROARK_API_KEY}'},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()

app.post('/webhooks/roark', async (req, res) => {
  const { event, data } = req.body
  if (event === 'call.analysis.completed') {
    const callId = data.callId

    const call = await get(`/v1/call/${callId}`)
    const metrics = await get(`/v1/call/${callId}/metrics`)

    await s3.putObject({
      Bucket: 'my-roark-export',
      Key: `calls/${callId}.json`,
      Body: JSON.stringify({ call, metrics }),
    })
  }
  res.sendStatus(200)
})

const get = async (path: string) => {
  const r = await fetch(`https://api.roark.ai${path}`, {
    headers: { Authorization: `Bearer ${process.env.ROARK_API_KEY}` },
  })
  if (!r.ok) throw new Error(`${path} -> ${r.status}`)
  return r.json()
}

Approach B: Scheduled backfill / poll

Best for the initial backfill of historical data, or as a simpler alternative to webhooks. Page through the calls list on a schedule and fetch metrics per call. The list endpoint uses keyset (cursor) pagination. Sort by startedAt and walk the cursor to move forward in time.

def export_all_calls():
    cursor = None
    while True:
        params = {'limit': 100, 'sortBy': 'startedAt', 'sortDirection': 'asc'}
        if cursor:
            params['after'] = cursor

        page = get('/v1/call', params=params)
        for call in page['data']:
            metrics = get(f"/v1/call/{call['id']}/metrics")
            write_to_s3(call, metrics)

        if not page['hasMore']:
            break
        cursor = page['nextCursor']

curl -G "https://api.roark.ai/v1/call" \
  -H "Authorization: Bearer $ROARK_API_KEY" \
  --data-urlencode "limit=100" \
  --data-urlencode "sortBy=startedAt" \
  --data-urlencode "sortDirection=asc" \
  --data-urlencode "after=$CURSOR"

For a large backfill you can also pull metric values a whole job at a time with GET /v1/metric/collection-jobs/{jobId}/metric-values, which returns every metric value for that collection job in one paginated stream rather than one request per call.

Loading into Snowflake

Land the raw JSON in an external stage, ingest into a VARIANT staging table, then flatten into modeled tables with LATERAL FLATTEN. Storing the raw payload first means a new metric or field never breaks your pipeline.

Create an external stage over your bucket

create or replace stage roark_stage
  url = 's3://my-roark-export/calls/'
  storage_integration = my_s3_integration
  file_format = (type = json);

Auto-ingest with Snowpipe

create table roark_raw (raw variant, loaded_at timestamp_ntz default current_timestamp());

create or replace pipe roark_pipe auto_ingest = true as
  copy into roark_raw (raw) from @roark_stage;

Flatten metrics into a queryable table

create or replace view roark_call_metrics as
select
  raw:call:id::string           as call_id,
  raw:call:externalId::string   as external_id,   -- your join key
  raw:call:startedAt::timestamp as started_at,
  raw:call:durationMs::number   as duration_ms,
  raw:call:callDirection::string as direction,
  m.value:slug::string          as metric_slug,
  m.value:name::string          as metric_name,
  m.value:type::string          as metric_type,
  m.value:value::variant        as metric_value,
  m.value:captureStatus::string as capture_status
from roark_raw,
  lateral flatten(input => raw:metrics:data) m;

Join against your operational data

-- Does call frustration predict whether a caregiver takes a shift?
select
  f.metric_value::float as frustration,
  s.shift_accepted
from roark_call_metrics f
join shifts s
  on s.roark_external_id = f.external_id
where f.metric_slug = 'frustration';

Model the flattened view once per metric type you care about, or keep one long-format (call_id, metric_slug, metric_value) table and pivot in your BI layer. Long format handles new metrics with zero schema changes.

Things to know

Idempotency. Keying S3 objects and Snowflake rows by callId (plus the metric collection job id) makes re-delivery and backfills safe to re-run without double counting.
Webhook delivery. Roark retries failed deliveries up to 3 times with backoff. Respond 200 within 5 seconds and process asynchronously. See Webhooks.
Date filtering. The calls list does not yet accept an explicit from/to date range. Approximate a range by sorting on startedAt and walking the cursor until you pass your window.
Transcripts are fetched per call from the transcript endpoint; they are not included in the metrics payload.
Rate limits and pagination. Use limit=100 and honor nextCursor/hasMore rather than assuming a fixed page count.

Deeper integrations

The pattern above uses only what is available today. If you need something more managed, we are building toward it and would like to scope it with you:

Managed connector

A Fivetran / Airbyte-style connector with incremental, updated-since cursors so your warehouse stays in sync automatically.

Scheduled file drop

Roark writes incremental Parquet or CSV to your own S3 bucket on a schedule, ready for Snowpipe.

Secure data share

A hands-off Snowflake Secure Data Share so there is nothing to run on your side.

Talk to us

Tell us your volume, latency needs, and the joins you want to run.

Next steps

Webhooks

Set up the analysis-completed notification

API Keys

Create a read-only key for the export

API Reference

Full endpoint and parameter reference

Reports

Analyze the same data inside Roark

Getting Started

Observability

Metrics

Simulations

Config as Code

Recipes

Integrations

SDKs & Libraries

Resources

Exporting to Snowflake

Overview

The recommended pattern

What you can export

Approach A: Event-driven (recommended for ongoing sync)

Approach B: Scheduled backfill / poll

Loading into Snowflake

Things to know

Deeper integrations

Managed connector

Scheduled file drop

Secure data share

Talk to us

Next steps

Webhooks

API Keys

API Reference

Reports

​Overview

​The recommended pattern

​What you can export

​Approach A: Event-driven (recommended for ongoing sync)

​Approach B: Scheduled backfill / poll

​Loading into Snowflake

​Things to know

​Deeper integrations

Managed connector

Scheduled file drop

Secure data share

Talk to us

​Next steps

Webhooks

API Keys

API Reference

Reports

Overview

The recommended pattern

What you can export

Approach A: Event-driven (recommended for ongoing sync)

Approach B: Scheduled backfill / poll

Loading into Snowflake

Things to know

Deeper integrations

Next steps