> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Snowflake CoWork

> Use Snowflake CoWork to explore your Hightouch models and audiences using natural-language questions powered by your warehouse.

## Before you begin

* A Snowflake account with required privileges (e.g., ACCOUNTADMIN or equivalent role to create Network Rules, Secrets, and Integrations).
* A Hightouch API key.
* At least one model configured in Hightouch.

## Overview

[**Snowflake CoWork**](https://www.snowflake.com/en/product/snowflake-cowork/) is Snowflake’s Enterprise Intelligence Agent, conversational AI assistant that helps you explore warehouse data and connected systems using natural language.

By integrating Snowflake CoWork with Hightouch, you can ask questions about your Customer Studio models, customer segments, activation campaigns, and audience performance directly from Snowflake.

This guide explains how to let Snowflake CoWork fetch **Hightouch model metadata** (such as model name, description, and query type) using the Hightouch [**Models API**](https://docs.hightouch.com/api-reference/list-models.md).

## How Snowflake CoWork works with Hightouch

Snowflake CoWork can call external APIs using Snowflake’s **External Access Integrations (EAIs)**.

When you authorize Snowflake to call the Hightouch Models API, Snowflake CoWork can:

* Retrieve a list of your Hightouch models
* Identify which models power visual audiences
* Read model descriptions and query types
* Reference this metadata when answering user questions

Hightouch continues to remain the system of record for model definitions—Snowflake only receives the metadata needed to answer questions.

> [!NOTE]
>
> Snowflake CoWork does *not* modify, create, or run Hightouch models.\
> It simply enriches your warehouse-level conversations with Hightouch model context.

## Example questions you can ask

Once connected, Snowflake CoWork can answer questions such as:

* "What audiences have we built that target churned customers?"
* "Which segments am I sending to my email platform?"
* “Which of my audiences was updated most recently?”

## Example setup: Calling the Hightouch Models API from Snowflake CoWork

This example shows how to configure Snowflake CoWork to call the Hightouch Models API.

You can extend this pattern to connect Snowflake CoWork with other Hightouch APIs like our Destinations API for activation insights or Events API for real-time customer behavior, creating a comprehensive conversational interface.

### 1. Use a Snowflake role with integration privileges

```sql theme={null}
USE ROLE ACCOUNTADMIN;
USE DATABASE DEMO_DB;
USE SCHEMA PUBLIC;
```

### 2. Create a network rule

Allows Snowflake to connect to the Hightouch API.

```sql theme={null}
CREATE OR REPLACE NETWORK RULE hightouch_rule
  MODE = egress
  TYPE = host_port
  VALUE_LIST = ('api.hightouch.com:443');
```

### 3. Create a secret with your Hightouch API key

```sql theme={null}
CREATE OR REPLACE SECRET hightouch_api_key
  TYPE = generic_string
  SECRET_STRING = '<API_KEY>';
```

> [!NOTE]
>
> **Note:** Replace `<API_KEY>` with your actual Hightouch API key. Create an API key in your [workspace settings →](https://app.hightouch.com/settings/api-keys?from=docs).

### 4. Create the External Access Integration

```sql theme={null}
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION hightouch_eai
  ALLOWED_NETWORK_RULES = (hightouch_rule)
  ALLOWED_AUTHENTICATION_SECRETS = (hightouch_api_key)
  ENABLED = TRUE;
```

### 5. Create a stored procedure to call the Hightouch Models API

```sql theme={null}
CREATE OR REPLACE PROCEDURE CALL_HIGHTOUCH_API()
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.10'
PACKAGES = ('requests','snowflake-snowpark-python')
EXTERNAL_ACCESS_INTEGRATIONS = (HIGHTOUCH_EAI)
SECRETS = ('cred' = HIGHTOUCH_API_KEY)
HANDLER = 'main'
AS
$$
import _snowflake
import requests
import json

def main():
    """
    Calls the Hightouch models endpoint
    """
    api_key = _snowflake.get_generic_secret_string('cred')
    url = "https://api.hightouch.com/api/v1/models"
    headers = {
        "Authorization": f"Bearer {api_key}",
    }

    try:
        resp = requests.get(url, headers=headers, timeout=30)
        resp.raise_for_status()
        return json.dumps(resp.json())
    except Exception as e:
        return f"Error: {str(e)}"
$$;
```

### 6. Test your connection

```sql theme={null}
CALL CALL_HIGHTOUCH_API();
```

You should receive a JSON list of your Hightouch models.

> [!NOTE]
>
> If you receive an empty response, verify that the API key’s user has access to Models in Hightouch.

## Enable Snowflake CoWork to use the procedure

Create a Snowflake CoWork agent that can call the stored procedure.

```sql theme={null}
CREATE OR REPLACE AGENT hightouch_agent
WITH PROFILE='{ "display_name": "Hightouch Agent" }'
COMMENT=$$ Enables users to interact with the Hightouch API $$
FROM SPECIFICATION
$$
{
  "models": { "orchestration": "auto" },
  "orchestration": {},
  "instructions": {
    "orchestration": "This is a simple agent for general knowledge with access to the Hightouch API"
  },
  "tools": [
    {
      "tool_spec": {
        "type": "generic",
        "name": "hightouch_models",
        "description": "{\n \"name\": \"hightouch_models\",\n \"description\": \"Fetch Hightouch models. If the user asks about audiences, they are referring to models with query_type = 'visual'\",\n \"parameters\": { \"type\": \"object\", \"properties\": {}, \"required\": [] },\n \"example_payload\": {},\n \"stored_proc_call\": \"CALL CALL_HIGHTOUCH_API();\"\n }",
        "input_schema": { "type": "object", "properties": {}, "required": [] }
      }
    }
  ],
  "tool_resources": {
    "hightouch_models": {
      "execution_environment": { "type": "warehouse", "warehouse": "" },
      "identifier": "DEMO_DB.PUBLIC.CALL_HIGHTOUCH_API",
      "name": "CALL_HIGHTOUCH_API",
      "type": "procedure"
    }
  }
}
$$;
```

## Troubleshooting

| Issue | Likely cause | Resolution |
| - | - | - |
| Empty API response | API key lacks required permissions | Use an admin-level API key or adjust permissions |
| Network rule error | Incorrect host or missing port | Ensure `api.hightouch.com:443` is configured |
| “EAI not found” | Integration wasn’t created in the active database/schema | Recreate using the same database/schema as the procedure |
| Snowflake agent cannot call the procedure | Missing tool spec or stored procedure reference | Recreate the agent using the example spec |

## Next steps

* [Explore your Hightouch models](https://docs.hightouch.com/models/creating-models.md)
* [Learn more about the Hightouch Models API](https://docs.hightouch.com/api-reference/list-models.md)
* [Review Snowflake's guide to Snowflake CoWork](https://www.snowflake.com/en/product/snowflake-cowork/)