> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following https://api.getcargo.io/INSTALL.md` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://raw.githubusercontent.com/getcargohq/cargo-skills/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# Advanced settings
Source: https://docs.getcargo.ai/agents/advanced

LLM selection, behavioral tuning, structured output, evaluators, triggers, and heartbeats — everything else on defineAgent.

Beyond the prompt and actions, `defineAgent` carries the agent's LLM binding and its behavioral settings:

```ts agents/qualifier.ts theme={null}
export const qualifier = defineAgent("qualifier", {
  connector: openai, // the LLM provider connector
  languageModel: "gpt-4o", // the model slug
  systemPrompt: "Qualify leads against our ICP.",
  temperature: 0.2, // 0.0–0.2 deterministic, 0.7+ creative (default 0.2)
  maxSteps: 4, // reasoning-step budget (default 8)
  withReasoning: false, // extended thinking before acting (default false)
  output: { type: "text" }, // or a jsonSchema contract — see below
  evaluator: { rubric: "Did it correctly qualify the lead?", threshold: 0.8 },
  triggers: [
    { type: "cron", cron: "0 9 * * *", text: "Qualify yesterday's leads" },
  ],
});
```

<Note>
  `connector` and `languageModel` are both required — `defineAgent` throws at
  `plan` time if either is missing. The connector's integration (OpenAI,
  Anthropic, …) determines which model slugs are valid.
</Note>

***

## Coding agents

A coding agent runs inside a sandbox with a cloned repository. Set `harness` to the runtime (e.g. `claudeCode`, `cursor`) and `repository` to control what the sandbox clones.

### Automatic repository binding

**Omit `repository`** and `plan`/`deploy` fill it from the checkout they run in — the `owner/name` of your git `origin`, the remote's default branch, and this project's path inside the repo — with the connector taken from the project's GitHub `defineConnector`:

```ts connectors/github.ts theme={null}
export const github = defineConnector("github", {
  integration: "github",
  default: true,
});
```

```ts agents/coder.ts theme={null}
export const coder = defineAgent("coder", {
  harness: "claudeCode",
  systemPrompt: "Work on this repository.",
  // repository omitted → bound to this checkout's origin
});
```

Anything you declare wins, so a partial object is completed the same way and a full one is left alone. `plan` prints what it resolved (e.g. `agent:coder bound to acme/app#main in infra/`) and the resolved values are inside the content hash, so deploying the same code from a different repository is a real update.

### Edge cases

| Checkout                                                    | Behavior                                                        |
| :---------------------------------------------------------- | :-------------------------------------------------------------- |
| **No GitHub remote** (GitLab origin, no origin, not a repo) | The agent stays unbound with an empty sandbox; `plan` says so   |
| **GitHub remote but no GitHub connector**                   | An error — add one with `cargo-ai project add connector/github` |

### Opting out

Pass `repository: null` to force an unbound agent whatever the checkout says:

```ts theme={null}
export const coder = defineAgent("coder", {
  harness: "claudeCode",
  systemPrompt: "General coding assistant.",
  repository: null, // explicitly unbound
});
```

<Warning>
  **Breaking change** — a harness agent that omits `repository` in a project
  that has a GitHub connector was previously deployed unbound. It now binds on
  the next plan. Use `repository: null` to keep the old behaviour.
</Warning>

***

## Selecting a model

The `connector` handle picks the provider; `languageModel` picks the model slug within it. Cargo supports the leading LLM providers — OpenAI, Anthropic, and Google Gemini among them — each behind its own [connector](/connectors/overview).

List the model slugs a provider currently exposes rather than hardcoding from memory:

```bash theme={null}
cargo-ai connection integration get openAi   # → available actions and model slugs
```

| Task profile                                             | Recommended approach              |
| :------------------------------------------------------- | :-------------------------------- |
| **Complex analysis** (qualification, research synthesis) | The provider's most capable model |
| **Simple classification** (routing, tagging)             | A fast, low-cost model            |
| **High volume, low stakes**                              | Prioritize speed and cost         |
| **Low volume, high stakes**                              | Prioritize reasoning quality      |

<Tip>
  Start with a powerful model during development to understand what's possible,
  then optimize for cost/speed once the agent is working well.
</Tip>

***

## Behavioral parameters

### Reasoning steps (`maxSteps`)

The maximum number of logical sub-tasks the agent can perform to reach a conclusion. Defaults to `8`.

| Setting          | Effect                           | Use when                                 |
| :--------------- | :------------------------------- | :--------------------------------------- |
| **Low (1-3)**    | Fast, direct responses           | Simple lookups, single-action tasks      |
| **Medium (4-6)** | Balanced reasoning               | Most standard workflows                  |
| **High (7+)**    | Deep, multi-step problem solving | Complex research, multi-source synthesis |

<Warning>
  Higher reasoning steps increase latency and cost. Only increase if the agent
  is failing to complete tasks.
</Warning>

### Temperature

Controls the creativity and variability of outputs. Defaults to `0.2`.

| Temperature   | Behavior                           | Best for                                              |
| :------------ | :--------------------------------- | :---------------------------------------------------- |
| **0.0 - 0.2** | Deterministic, precise, consistent | Data extraction, classification, CRM updates          |
| **0.3 - 0.6** | Balanced creativity                | General tasks, qualification, research                |
| **0.7 - 1.0** | Creative, varied                   | Copywriting, brainstorming, conversational engagement |

### Extended thinking (`withReasoning`)

`withReasoning: true` lets the model think through the problem before acting — better on hard multi-step tasks, at the cost of latency and tokens. Defaults to `false`.

***

## Structured output

By default an agent answers in free text (`output: { type: "text" }`). To make every final answer machine-parseable — for workflows or API consumers downstream — declare a JSON Schema contract:

```ts theme={null}
output: {
  type: "jsonSchema",
  jsonSchema: {
    type: "object",
    properties: {
      score: { type: "string", enum: ["High", "Medium", "Low"] },
      reasoning: { type: "string" },
    },
    required: ["score", "reasoning"],
  },
},
```

***

## Evaluator

The `evaluator` is an LLM-as-judge that scores each of the agent's outputs against a natural-language rubric:

```ts theme={null}
evaluator: {
  rubric: "Did it correctly qualify the lead, with evidence for the score?",
  threshold: 0.8,   // passing bar in [0, 1]
},
```

Outputs scoring below `threshold` are flagged, so you can spot quality regressions without reading every conversation. Pair it with prompt iterations: change the `systemPrompt`, re-deploy, and compare evaluator pass rates.

***

## Triggers

Agents normally respond to messages, but `triggers` make them start work on their own:

```ts theme={null}
triggers: [
  // On a schedule — `text` is the message the agent receives
  { type: "cron", cron: "0 9 * * *", text: "Qualify yesterday's inbound leads." },

  // On a connector event (e.g. an incoming Slack message)
  agentConnectorTrigger({ connector: slack, config: { channel: "#inbound" } }),
],
```

A `connector` trigger references its connector by handle or `connectorRef(uuid)`; `config` is integration-specific. `agentConnectorTrigger` types that `config` against the integration's schema, which a bare object literal can't do — TypeScript won't infer a per-element type through an array. A `defineConnector` handle names its integration, so the helper reads it from there; pass `integration: "slack"` yourself when there's no handle to read it from, either because you're using `connectorRef(uuid)` or because the trigger names an integration with no specific connector.

The bare form still works, with `config` left as a loose object:

```ts theme={null}
{ type: "connector", integration: "slack", connector: slack, config: { channel: "#inbound" } }
```

***

## Heartbeat

A `heartbeat` wakes the agent up on an interval inside an ongoing chat — useful for long-running missions that should make progress without a human prompting each turn:

```ts theme={null}
heartbeat: {
  intervalMinutes: 30,   // delay between heartbeat turns
  maxMessages: 40,       // stop waking up once the chat has this many messages
  prompt: null,          // message sent each turn; null = a generic "continue"
},
```

***

## Optimizing for cost and speed

Once your agent works correctly, consider:

1. **Reduce `maxSteps`** if tasks complete in fewer steps
2. **Try a faster model** and verify quality remains acceptable (the `evaluator` pass rate is the signal)
3. **Lower `temperature`** for more predictable outputs
4. **Limit resources** to reduce context size and processing time


# Native LLM Capabilities
Source: https://docs.getcargo.ai/agents/native-llm-capabilities

Built-in features that enhance your Agent's reasoning, memory, and ability to interact with users and data.

Capabilities are native features of the underlying LLM that extend what your Agent can do—beyond just processing instructions and calling actions.

Enable them with the `capabilities` array on `defineAgent`. Each entry is a capability slug (or a `{ slug, config }` object for ones that take options):

```ts agents/researcher.ts theme={null}
export const researcher = defineAgent("researcher", {
  connector: openai,
  languageModel: "gpt-4o",
  systemPrompt: "Research accounts and produce a shareable brief.",
  capabilities: ["webSearch", "memory", "document", "suggestedActions"],
});
```

The full set of slugs: `webSearch`, `memory`, `document` (Canvas), `suggestedActions`, `file`, `model`, `documentationSearch`, `sandbox`, and `context`. The sections below explain the most common ones and when to enable them.

`file` and `model` are enabled automatically when files or models are attached to the Agent, so you rarely list them by hand. `file` covers listing, reading, searching and analysing files — analysing runs code over them in a sandbox, which is what the separate `codeInterpreter` slug used to do.

***

## Available capabilities

### Memory

Memory allows Agents to retain and recall information across interactions, enabling personalization and continuity.

| Memory type          | Scope                    | Use case                                                                            |
| :------------------- | :----------------------- | :---------------------------------------------------------------------------------- |
| **User Memory**      | Persists per end-user    | Stores preferences, past interactions, and personal context for tailored responses  |
| **Workspace Memory** | Shared across all Agents | Organizational knowledge like company policies, ICP definitions, or team guidelines |
| **Agent Memory**     | Current execution only   | Short-term context including previous steps and action outputs within a single run  |

<Tip>
  Use Workspace Memory for information that all Agents should know—like your ICP
  criteria or product positioning.
</Tip>

***

### Web Search

Gives Agents access to real-time information from the internet.

**When to enable:**

* Account research requiring current market data
* Validating company information that may have changed
* Finding recent news, funding announcements, or leadership changes

**Example query:**

> "What is the latest funding round for Acme Corp?"

***

### Canvas

Enables Agents to generate structured, shareable digital assets. The capability
slug is `document` (surfaced as **Canvas** in the web app).

**Supported outputs:**

* Spreadsheets and CSV files
* Text documents
* Formatted reports

**Example use case:**
A user asks: *"Give me a list of CROs in San Francisco."*

The Agent researches, compiles the data, and delivers a formatted spreadsheet—ready to download or share.

***

### Suggested Actions

A proactive assistant that recommends the next best step after completing a task.

**How it works:**

1. Agent completes the requested task
2. Analyzes what logical next steps might help the user
3. Offers actionable suggestions

**Example:**
After retrieving a list of contacts, the Agent suggests:

> "Would you like me to add these contacts to Sequence XX?"
> "Should I enrich these contacts with email addresses?"

<Note>
  Suggested Actions keep workflows moving and help users discover capabilities
  they might not have thought to request.
</Note>

***

## Enabling capabilities

Toggle capabilities on or off based on your Agent's purpose:

| Agent type                   | Recommended capabilities   |
| :--------------------------- | :------------------------- |
| **Research Agent**           | Memory, Web Search, Canvas |
| **Qualification Agent**      | Memory, Suggested Actions  |
| **CRM Updater**              | Memory only                |
| **Conversational Assistant** | All capabilities           |

<Warning>
  More capabilities = more complexity. Only enable what your Agent actually
  needs to avoid unpredictable behavior.
</Warning>


# Overview
Source: https://docs.getcargo.ai/agents/overview

LLM-powered workers that reason, research, and act. Define them with defineAgent — wiring in tools, data models, sub-agents, and connector actions through one `uses` array.

An **agent** is an AI worker that plans and executes multi-step tasks. Unlike a play (a fixed sequence), an agent reasons over its instructions and the tools, data, and sub-agents you give it. You define one with `defineAgent`.

## Define an agent

Every capability is passed as a handle, so Cargo deploys dependencies first and injects their uuids:

```ts agents/sdr.ts theme={null}
import { defineAgent } from "@cargo-ai/cdk";
import { hunter } from "../connectors/hunter";
import { openai } from "../connectors/openai";
import { contacts } from "../models/contacts";
import { enrich } from "../tools/enrich";
import { enricher } from "./enricher";

export const sdr = defineAgent("sdr", {
  connector: openai, // the LLM provider (not a `use`)
  languageModel: "gpt-4o",
  systemPrompt:
    "You qualify inbound leads, enrich missing contact info, and route hot leads to Slack.",
  maxSteps: 12,
  capabilities: ["webSearch", "memory"],
  // Everything the agent can call or read — one array, kind inferred per handle:
  uses: [
    { ref: contacts, readOnly: true }, //          a data model
    enrich, //                                     a tool
    { ref: enricher, waitUntilFinished: true }, //  a sub-agent
    hunter.actions.findEmail, //                           a connector action
  ],
  triggers: [{ type: "cron", cron: "0 9 * * *", text: "Daily qualification" }],
  evaluator: { rubric: "Did it correctly qualify the lead?", threshold: 0.8 },
});
```

## Anatomy

| Field                                                    | Role                                                                                 | Learn more                                                                                         |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `systemPrompt`                                           | The agent's mission and constraints                                                  | [Prompt](/agents/prompt)                                                                           |
| `capabilities`                                           | Built-in LLM features (web search, memory, …)                                        | [Native LLM capabilities](/agents/native-llm-capabilities)                                         |
| `uses`                                                   | Everything it can invoke or read — tools, connector actions, sub-agents, data models | [Tools & actions](/agents/tools-and-actions), [Resources & context](/agents/resources-and-context) |
| `connector` / `languageModel` / `maxSteps` / `evaluator` | LLM provider and behavior                                                            | [Advanced settings](/agents/advanced)                                                              |

Each `uses` entry is a handle — its kind is read from the handle, so order doesn't matter. Pass a bare handle, or `{ ref, …options }` to tune it: tools / sub-agents / connector actions take `{ name, description, isBulkAllowed, config }`, with `waitUntilFinished` on tools and sub-agents only; a data model takes `{ readOnly, columns }`. A connector action is an action off a connector handle — `hunter.actions.findEmail`.

## Deploy and chat

```bash theme={null}
cargo-ai project deploy
cargo-ai ai agent list                    # → agentUuid
cargo-ai ai chat create --agent-uuid <uuid> --trigger '{"type":"draft"}' --name "My chat"
cargo-ai ai message create --chat-uuid <uuid> \
  --parts '[{"type":"text","text":"Qualify acme.com"}]' --wait-until-finished
```

## Where agents run

Agents can be triggered from plays (scheduled or change-driven), Slack mentions, the Chrome extension, embedded chat, or a CRM button. Bundle them behind an [MCP server](/mcp-servers/overview) to expose them to external assistants.

## Using the UI

Prefer to build visually? See [Using the UI](/agents/using-ui) for the Instructions / Actions / Resources walkthrough. Agents built in code and in the UI are interchangeable.


# Prompt
Source: https://docs.getcargo.ai/agents/prompt

The systemPrompt is the foundation of an agent's behavior — its mission, approach, and constraints, versioned in code.

The prompt tells your agent who it is, what it should do, and what it should avoid. A well-crafted prompt is the difference between an agent that delivers consistent, high-quality results and one that produces unpredictable outputs.

The prompt is the `systemPrompt` field on `defineAgent`. Keep it in code so it's versioned and reviewable:

```ts agents/qualifier.ts theme={null}
export const qualifier = defineAgent("qualifier", {
  connector: openai,
  languageModel: "gpt-4o",
  systemPrompt: `ROLE:
You are a lead qualification specialist for Cargo. Evaluate inbound leads
against our ICP and score their fit.

BEHAVIOR:
1. Extract the company domain from the lead's email.
2. Use the enrichment action to gather firmographics.
3. Score the lead as "High", "Medium", or "Low" fit.
4. Return JSON: { score, reasoning, nextStep }.

AVOIDANCES:
- Do not qualify personal email domains (gmail, yahoo, …).
- Never fabricate data — if enrichment fails, mark "Needs Review".`,
  uses: [enrich],
});
```

The rest of this page is guidance on writing that string well.

## The three components

Every agent prompt consists of three sections:

### 1. Role / Purpose

Defines **who the agent is** and **what it's trying to achieve**. This sets the primary context for the LLM.

<Tip>
  Keep this concise and focused on the end goal. One or two sentences is ideal.
</Tip>

**Example:**

```
You are a lead qualification specialist for Cargo. Your job is to evaluate
LinkedIn company URLs and determine if they match our Ideal Customer Profile.
```

### 2. Behavior

Outlines **how the agent should work** — the steps it takes, actions it uses, and the format of its output. This directly guides the agent's planning phase.

**Example:**

```
1. Use the "Company-Lookup" action to retrieve company data from the URL
2. Check the company against our ICP criteria in the Knowledge Base
3. Assign a qualification score: "High Fit", "Medium Fit", or "No Fit"
4. Provide a 2-3 sentence explanation of your reasoning
```

<Note>
  **Action selection tip**: Give each action a specific name and clear description.
  The agent uses these to decide which action to call and when.
</Note>

### 3. Avoidances

Establishes **what the agent must NOT do**. These guardrails prevent undesired actions and ensure compliance.

**Example:**

```
- Never share proprietary ICP criteria with external parties
- Do not make up information if a lookup fails—report the failure instead
- Avoid overly casual language; maintain a professional tone
```

<Warning>
  Avoidances are critical for security, compliance, and maintaining trust. Be
  explicit about sensitive data handling and edge cases.
</Warning>

***

## Best practices

| Practice                 | Why it matters                                                                                                                                                 |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Be specific**          | Vague instructions lead to inconsistent results. Say "assign a score of 1-10" instead of "rate the lead"                                                       |
| **Define output format** | Specify what the agent should return — or enforce it with `output: { type: "jsonSchema", … }` (see [Advanced settings](/agents/advanced#structured-output))    |
| **List actions by name** | Reference the exact action names so the agent knows what's available                                                                                           |
| **Handle edge cases**    | Tell the agent what to do when data is missing or an action fails                                                                                              |
| **Test iteratively**     | Run test queries and refine the prompt based on actual outputs — an [`evaluator`](/agents/advanced#evaluator) can score outputs against a rubric automatically |

***

## Next steps

<CardGroup>
  <Card title="Tools & actions" icon="wrench" href="/agents/tools-and-actions">
    Give the agent operations to invoke — tools, connector actions, sub-agents, MCP servers.
  </Card>

  <Card title="Native LLM capabilities" icon="sparkles" href="/agents/native-llm-capabilities">
    Web search, memory, canvas, and the other built-in features.
  </Card>
</CardGroup>


# Resources & context
Source: https://docs.getcargo.ai/agents/resources-and-context

Ground an agent in your data — models wired through defineAgent, files searched by vector similarity, and the context repository.

Resources give your agent access to your organization's data — CRM records, knowledge bases, product databases, and more. This is called **RAG** (Retrieval-Augmented Generation): the agent retrieves relevant information before generating responses.

In code, structured data is wired through the agent's `uses` array (alongside its tools and actions); unstructured content comes from [files](/files/overview) attached to the workspace:

```ts agents/support.ts theme={null}
export const support = defineAgent("support", {
  connector: openai,
  languageModel: "gpt-4o",
  systemPrompt: "Answer using our CRM data and playbooks; never invent facts.",
  uses: [
    {
      ref: deals, //                          a defineModel handle
      readOnly: true, //                      don't let it write back
      columns: ["name", "stage", "amount"], // narrow the surface
    },
  ],
});
```

A data model in `uses` is a model handle (or `modelRef(uuid)`), bare or wrapped as `{ ref, readOnly, columns }` — its kind is read from the handle, so it sits in the same array as the agent's tools and actions. Without resources, an agent only knows its instructions and what web search returns.

***

## Types of resources

There are two types of resources you can connect to your agent:

| Type                           | Data format       | Examples                                         |
| :----------------------------- | :---------------- | :----------------------------------------------- |
| [**Models**](/models/overview) | Structured data   | CRM objects, product databases, SQL tables       |
| [**Files**](/files/overview)   | Unstructured data | PDFs, documents, transcripts, knowledge articles |

### Models

Models connect your agent to **structured data** — tables with rows and columns. The agent queries this data using SQL, making it ideal for filtering, sorting, and aggregating records.

**Best for:**

* CRM Objects (HubSpot Deals, Salesforce Accounts, Attio Records)
* Product Data (usage databases, analytics platforms)
* Custom Databases (BigQuery, Snowflake)

### Files

Files connect your agent to **unstructured data** — documents, PDFs, and text content. You select which files or folders to include, and the agent searches this content using vector similarity to find relevant information.

**Best for:**

* Knowledge Bases (Notion, Google Docs, uploaded files)
* Playbooks, FAQs, and process documentation
* Meeting transcripts and call notes

When a workspace has a **context repository** configured, non-temporary files from the workspace Files library are also mirrored under `.files/` in that repo (preserving folder structure). That tree is **read-only** in the context runtime — agents can read mirrored files but cannot write, edit, or auto-commit changes under `.files/`. Update files in the Files library; Cargo syncs them into context.

***

## Configuring a model resource

### In code

The `{ ref, …options }` wrapper covers the settings that matter most:

| Option     | Effect                                                        |
| :--------- | :------------------------------------------------------------ |
| `readOnly` | Block writes back to the model (defaults to `true` on agents) |
| `columns`  | Only expose these column slugs — less noise, better reasoning |

### In the UI

The agent's Resources tab adds settings that don't have a code equivalent yet — configure these in the UI after deploying:

| Setting        | Description                                                                            |
| :------------- | :------------------------------------------------------------------------------------- |
| **Query mode** | **SQL** (filter, sort, aggregate) or **Vector** (semantic similarity over text fields) |
| **Filters**    | Restrict which records the agent can access                                            |
| **Limit**      | Maximum number of records returned per query                                           |

**SQL example:**

> "Find all deals in the Discovery stage with value over \$50k"

**Vector example:**

> "Find companies with product descriptions similar to AI automation"

<Warning>
  UI-configured settings on a code-managed agent are overwritten if you later
  change that agent in code and re-deploy — see [Code and UI
  round-trips](/deploy/state-and-drift#code-and-ui-round-trips).
</Warning>

***

## Configuring files

File resources are selected in the UI today (the agent's Resources tab): choose the files or folders to include, and the agent searches all selected content by vector similarity. The resource description guides how the agent interprets or prioritizes the content:

```
This folder contains our sales playbooks. Prioritize the
objection handling guide when the user asks about pricing concerns.
```

Upload and organize the underlying files from code and the CLI — see [Files](/files/overview).

***

## Best practices

<CardGroup>
  <Card title="Start with filters">
    Narrow down data access to what the agent actually needs. Less noise =
    better reasoning.
  </Card>

  <Card title="Write clear descriptions">
    Help the agent understand how to query your data and what matters most.
  </Card>

  <Card title="Choose the right query mode">
    For models, use SQL for filtering and aggregating, Vector for semantic
    search.
  </Card>

  <Card title="Test before deploying">
    Run test prompts to verify the agent retrieves the right data.
  </Card>
</CardGroup>

***

## Learn more

<CardGroup>
  <Card title="Models" icon="table" href="/models/overview">
    Learn how to build and manage structured data models.
  </Card>

  <Card title="Files" icon="file" href="/files/overview">
    Work with documents, PDFs, and unstructured content.
  </Card>
</CardGroup>


# Tools & actions
Source: https://docs.getcargo.ai/agents/tools-and-actions

Give an agent callable operations — your tools, connector actions, sub-agents, and MCP servers — on defineAgent.

Actions transform your agent from a reasoning engine into an action-taker. In code, you give an agent its callable capabilities — your tools, connector actions, and sub-agents — in one `uses` array on `defineAgent` (external MCP servers are a separate `mcpClients` field):

```ts agents/sdr.ts theme={null}
export const sdr = defineAgent("sdr", {
  connector: openai,
  languageModel: "gpt-4o",
  systemPrompt: "Qualify inbound leads and route hot ones to Slack.",

  uses: [
    enrich, //                                                    your tool (a defineTool handle)
    { ref: scoreLead, description: "Score ICP fit 1–10.", isBulkAllowed: true },
    hunter.actions.findEmail, //                                          an action off a connector handle
    { ref: researcher, waitUntilFinished: true }, //             a specialist sub-agent
  ],

  // External MCP servers whose tools the agent can call (a separate field)
  mcpClients: [{ kind: "custom", name: "notion", url: "https://mcp.notion.com/mcp", authentication: null, disabledToolSlugs: [] }],
});
```

Each `uses` entry is a handle — bare, or `{ ref, …options }`. Tools, connector actions, and sub-agents share the options `{ name, description, isBulkAllowed, config }`, and tools and sub-agents take `waitUntilFinished` on top; the `description` is the AI contract — the agent reads it to decide when to call the action. A connector action is an action off a `defineConnector` handle: `hunter.actions.findEmail`.

<Note>
  Connect an integration with [`defineConnector`](/connectors/overview) before
  referencing its actions, and see [Tools](/tools/overview) for building the
  tools you pass in. Run [`cargo-ai project types`](/get-started/project-layout) so
  a connector handle's action names (`hunter.<action>`) autocomplete from the
  real registry.
</Note>

## How actions work

When an agent receives a task, it:

1. **Analyzes** the goal and available actions
2. **Selects** the appropriate action(s) based on their descriptions
3. **Executes** the action with the right inputs
4. **Uses the output** to continue reasoning or complete the task

<Note>
  The action's **description** is critical. The agent reads this description to
  decide when and how to use the action. Write descriptions that clearly explain
  what the action does and when to use it.
</Note>

***

## Configuring an action

### Description (the AI contract)

This plain-language description tells the agent:

* **What** the action does
* **When** to use it
* **What inputs** it expects

**Good example:**

```
"Enriches a company using its domain. Returns firmographic data including
employee count, industry, funding, and tech stack. Use this when you need
company information for qualification or research."
```

**Poor example:**

```
"Gets company data"
```

### Fixed vs. agent-decided inputs

By default the agent decides every input field of an action at runtime, from conversation context and the action's description. To lock a field to a fixed value, set it in the action's `config` — anything you put there is sent as-is and never left to the agent. This works for connector actions, tools, and sub-agents alike:

```ts theme={null}
uses: [
  { ref: hubspot.actions.createRecords, config: { objectType: "deals" } }, // always deals — the agent fills in the rest
],
```

<Tip>
  Mix fixed and agent-decided fields when some inputs should always be the same
  (e.g., a specific CRM pipeline ID) while others depend on the conversation
  context (e.g., a lead's email address).
</Tip>

In the UI, each field additionally has a mode selector — **Default** (fixed value), **Auto** (agent decides), or **Disable** (field skipped entirely). Disabling a field is UI-only today; in code, fields are either fixed via `config` or agent-decided.

### Bulk execution

Set `isBulkAllowed: true` when the agent should apply the action across multiple records in a single run. Useful for batch operations like:

* Enriching a list of companies
* Updating multiple CRM records
* Sending notifications to several recipients

### Waiting for completion

`waitUntilFinished` (default `true`) blocks the agent until the action finishes so it can use the result. Set it to `false` for fire-and-forget calls — e.g. a tool that files a ticket the agent doesn't need to read back.

This applies to tools and sub-agents only: they run as a workflow the agent can either wait on or leave running. A connector action always runs inline, so there is nothing to not wait for — setting `waitUntilFinished` on one is a type error.

***

## Common action types

| Category          | Examples                     | Typical use                            |
| :---------------- | :--------------------------- | :------------------------------------- |
| **Enrichment**    | Clearbit, Apollo, FullEnrich | Gather company or contact data         |
| **CRM**           | Salesforce, HubSpot, Attio   | Create/update records, log activities  |
| **Communication** | Slack, Email, Outreach       | Send messages, add to sequences        |
| **Data lookup**   | Internal APIs, SQL queries   | Retrieve custom data from your systems |

***

## MCP servers

Cargo agents support the **Model Context Protocol (MCP)** — an open standard for connecting AI models to external actions and data sources. Declare the servers an agent can call with `mcpClients`; Cargo discovers and registers their tools automatically:

```ts theme={null}
mcpClients: [
  // Any MCP-compatible server, by URL
  { kind: "custom", name: "notion", url: "https://mcp.notion.com/mcp", authentication: null, disabledToolSlugs: [] },

  // An MCP server backed by one of your connectors (by uuid)
  { kind: "connector", name: "hubspot", connectorUuid: "9c26…", integrationSlug: "hubspotMcp", disabledToolSlugs: [] },
],
```

Use `disabledToolSlugs` to hide individual tools from the agent, and `authentication` to pass an OAuth token set for servers that require one (or `null` for unauthenticated servers). In the UI, the same thing is configured by pasting the server URL on the agent's Actions tab.

<Note>
  This is the agent **consuming** external MCP servers. To expose your own
  Cargo tools and agents *as* an MCP server, see
  [MCP servers](/mcp-servers/overview).
</Note>

***

## Best practices

<CardGroup>
  <Card title="Write clear descriptions">
    The agent relies on descriptions to choose actions. Be specific about what the
    action does and what it returns.
  </Card>

  <Card title="Name actions descriptively">
    Use names like `Enrich-Company` or `Slack-Notify-Rep` instead of generic
    names like `Action1`.
  </Card>

  <Card title="Handle failures gracefully">
    In your agent's instructions, specify what to do if an action call fails
    (retry, skip, report error).
  </Card>

  <Card title="Limit scope">
    Only give agents access to the actions they need. Fewer actions = faster, more
    accurate action selection.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup>
  <Card title="Connectors" icon="plug" href="/connectors/overview">
    Connect integrations with defineConnector before referencing their actions.
  </Card>

  <Card title="Tools" icon="wrench" href="/tools/overview">
    Build reusable tools with defineTool to pass into an agent.
  </Card>
</CardGroup>


# Using UI
Source: https://docs.getcargo.ai/agents/using-ui

Learn what agents are, and how to build your first one.

<iframe title="Build an agent in Cargo" />

## What are agents?

Agents are intelligent actors in Cargo that reason and answer open-ended questions relevant to your GTM processes. They use foundational AI models to leverage semantic reasoning to trigger the right set of actions, resources or MCP servers to achieve the task given to them.

Unlike Plays—which follow a pre-defined sequence of steps—Agents use a **reasoning engine** to dynamically determine the best path to a goal based on input context and available actions.

<Note>
  **Agents vs Plays**: Use a Play when your workflow is predictable and
  repeatable. Use an Agent when tasks require reasoning, adaptability, or
  handling variable inputs.
</Note>

Once set up, Cargo agents can be prompted from a variety of places, including a **Slack channel**, a **Chrome extension**, an **API endpoint** or a **Cargo play**.

## Use cases

Agents can be used for a variety of GTM tasks, including:

* **Automated research:** The agent can use its reasoning to sift through information on companies and people and retain the most relevant intelligence for the task at hand.
* **Lead and account qualification:** Qualify leads and accounts based on custom rules and real-time data.
* **Sales enablement:** Agents can use a wide-range of context about a deal or an incident, to provide guidance on the next best step to assist a sales team member's job.
* **CRM management:** Update fields, upsert records, and maintain data integrity across your systems.
* **Signal extraction:** Summarize conversations and identify product interest or objections.
* **Risk detection:** Proactively spot churn signals, usage drops, or job changes.

***

## Step-by-step: Build your first agent

Follow these steps to create an agent that qualifies leads based on your Ideal Customer Profile.

### Step 1: Create a new agent

1. Navigate to **Agents** in your Cargo workspace sidebar
2. Click **+ New Agent** in the top right corner
3. Give your agent a descriptive name (e.g., "Lead Qualification Agent")

<img alt="Creating a new agent" />

### Step 2: Define the instructions

The instructions tell your Agent who it is, what it should do, and what it should avoid. Click on the **Instructions** tab and define:

1. **Role / Purpose** — Who the Agent is and what it's trying to achieve
2. **Behavior** — The steps it takes, actions it uses, and the format of its output
3. **Avoidances** — What the Agent must NOT do

<img alt="Defining agent instructions" />

<Tip>
  Be specific in your instructions. Say "assign a score of 1-10" instead of "rate the lead". Vague instructions lead to inconsistent results.
</Tip>

### Step 3: Add actions

Actions give your Agent the ability to take action—updating CRMs, sending messages, and enriching data.

1. Click on the **Actions** tab
2. Select the actions your Agent needs (e.g., "Company Enrichment", "CRM Update")
3. Write clear descriptions for each action so the Agent knows when to use them

<img alt="Adding actions to your agent" />

### Step 4: Load resources

Resources are knowledge bases and data sources that ground the Agent's reasoning.

1. Click on the **Resources** tab
2. Add relevant documents, spreadsheets, or data sources (e.g., your ICP criteria)
3. The Agent will reference these during execution

### Step 5: Configure capabilities

Enable built-in LLM features that enhance your Agent:

* **Memory** — Remember context across conversations
* **Web Search** — Look up real-time information online
* **Canvas** — Generate and edit structured content

### Step 6: Test your agent

Before deploying, test your Agent:

1. Click the **Test** button
2. Enter a sample prompt (e.g., "Qualify this lead: acme.com")
3. Review the Agent's reasoning and actions
4. Refine the instructions based on the output

<img alt="Testing your agent" />

### Step 7: Deploy

Once everything works:

1. Click **Deploy** in the top right corner
2. Choose your deployment channels (Slack, Chrome extension, Play, CRM button)
3. Your Agent is now ready to use!

<img alt="Agent in action" />

***

## Best practices

* **Start with a focused goal** — Build Agents for specific tasks rather than general-purpose assistants. A lead qualification Agent will outperform a "do everything" Agent.
* **Write clear action descriptions** — The Agent reads action descriptions to decide when to use them. Be specific about what each action does and when to use it.
* **Handle edge cases** — Tell the Agent what to do when data is missing or an action fails. Don't let errors silently fail.
* **Test iteratively** — Run test queries and refine the instructions based on actual outputs. Small tweaks can significantly improve results.

***

## Next steps

<CardGroup>
  <Card title="Craft better instructions" icon="pencil" href="/agents/prompt">
    Master the art of writing Agent prompts that deliver consistent, high-quality results.
  </Card>

  <Card title="Integrate actions" icon="plug" href="/agents/tools-and-actions">
    Connect your Agent to CRMs, enrichment services, and communication platforms.
  </Card>

  <Card title="Load resources" icon="database" href="/agents/resources-and-context">
    Ground your Agent with knowledge bases and data sources.
  </Card>

  <Card title="Advanced settings" icon="sliders" href="/agents/advanced">
    Fine-tune LLM provider, temperature, reasoning, and execution limits.
  </Card>
</CardGroup>


# Events
Source: https://docs.getcargo.ai/alerts/events

Every alert evaluation records one event — the value it computed, the verdict, and the runs it fired.

Every evaluation of an [alert](/alerts/overview) writes exactly one **event**, whether or not it breached. The event stream is the alert's history: what the metric was each time it was checked, when it fired, and which runs it spawned.

## Statuses

| Status      | Meaning                                                                                                                                             |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `healthy`   | Evaluated fine and the threshold was not breached. Also the status when there was nothing to judge — `value` is then `null`.                        |
| `unhealthy` | The value breached the threshold. The alert's actions were fired, and their run uuids are on the event.                                             |
| `error`     | The value could not be computed — a failed scope query, for instance. There is no verdict: `value` is `null` and `errorMessage` carries the reason. |

An `error` event still advances the alert's window, so a broken query doesn't
pile up a backlog to re-evaluate once it's fixed.

## What an event carries

Alongside `status`, `value`, and `errorMessage`, each event records the window it
judged (`windowStartedAt` / `windowEndedAt`) and `runUuids` — one run per action
fired, empty unless the event is `unhealthy`.

An event also **snapshots the alert as it was evaluated**: its scope, threshold,
and actions are copied onto the event rather than read back from the live alert.
Editing an alert's threshold, or deleting the alert entirely, therefore doesn't
rewrite the meaning of its past events — a firing from last week still shows the
threshold it actually breached.

## Read the history

```bash theme={null}
cargo-ai observability event list <alert-uuid>
```

In the web app, open an alert and switch to the **Events** tab. Events are listed
newest first with their status, computed value, and window, filterable by status;
expanding a firing lists the runs it spawned so you can jump straight into what
the alert set off.

<Tip>
  A run of `healthy` events with `value: null` means there was nothing to judge:
  the scope matched no spans or runs, or (for `errorRate` and `duration`) none
  that had finished yet, or a query scope returned no rows or a `NULL`. That is
  usually a scope that is too narrow, or a workflow that
  has stopped running, which a `count` / `lte` alert would catch as a breach. See
  the dead-man's switch note in [Overview](/alerts/overview#threshold-when-it-breaches).
</Tip>


# Overview
Source: https://docs.getcargo.ai/alerts/overview

Scheduled threshold checks over your telemetry, your warehouse SQL, or a model's records, firing actions when a metric breaches. Define them with defineAlert.

An **alert** is a scheduled check over your workspace. On each tick it computes one metric over a slice of your data, compares it to a threshold, and, when the threshold is breached, fires its actions, each as its own run. You define one with `defineAlert`.

What it measures is up to the scope: [span telemetry](/deploy/monitoring#spans-and-traces) (every tool run, play batch and agent message emits spans), your play and tool **runs** end to end, a raw **SQL** query against the orchestration store or your data warehouse, or the records of a **model**.

## Define an alert

```ts alerts/error-spike.ts theme={null}
import { defineAlert } from "@cargo-ai/cdk";

import { sentinel } from "../agents/sentinel";
import { slack } from "../connectors/slack";
import { enrich } from "../tools/enrich";

export const errorSpike = defineAlert("error-spike", {
  description: "Error rate of the enrich workflow",
  schedule: { type: "cron", cron: "@every 5m" }, // when the check runs
  scope: { kind: "spans", workflow: enrich }, // which spans it watches
  threshold: { metric: "errorRate", operator: "gte", value: 10 }, // when it breaches
  actions: [
    {
      ref: slack.actions.postMessage,
      config: {
        channelId: "C0123456789",
        format: "markdown",
        body: "Enrich error rate hit {{event.value}}% — {{event.spansUrl}}",
      },
    },
    { ref: sentinel, config: { prompt: "Investigate {{alert.url}}" } },
  ],
});
```

`schedule` takes a 5-field cron expression or an `@every` interval (`@every 5m`, `@every 1h30m`), evaluated in UTC. An alert evaluates **at most once a minute** — every tick scans your spans, so sub-minute intervals are rejected. In a project `enabled` defaults to `true`, so a deployed alert is armed; set it to `false` to deploy one without arming it. `folder` files the alert under an `"alert"`-kind [folder](/folders/overview).

## Scope: what it watches

The scope's `kind` names the data source. Each source pairs with its own metric menu, so a metric can never be asked of a source that can't compute it.

### Spans scope

`kind: "spans"` watches span telemetry directly. Use any subset of these filters; omitted fields don't narrow. They mirror the **Spans** view.

| Field                          | Narrows to                                                              |
| ------------------------------ | ----------------------------------------------------------------------- |
| `workflow`                     | one play or tool's workflow: a handle, or `workflowRef(uuid)`           |
| `parentAgent`                  | the spans of runs one agent spawned                                     |
| `nodeKind`                     | `native`, `connector`, `tool`, or `agent` nodes                         |
| `integration`                  | one integration slug                                                    |
| `connector`                    | one connector                                                           |
| `action`                       | one action slug                                                         |
| `tool`                         | one tool *node*                                                         |
| `agent`                        | one agent *node*                                                        |
| `executionTitleOrErrorMessage` | spans whose title or error message contains the text (case-insensitive) |
| `executionStatuses`            | `pending`, `success`, and/or `error`                                    |
| `userUuid`                     | runs started by one user                                                |

<Note>
  `parentAgent` and `agent` are different filters. `parentAgent` matches spans
  of runs an agent *started* — the agent-trigger case. `agent` matches an agent
  *node* running inside the watched spans.
</Note>

<Warning>
  `workflow` takes a play/tool handle or `workflowRef(uuid)` — not `toolRef` or
  `agentRef`. Spans are keyed by the workflow behind a tool, not by the tool's
  own uuid, so passing the wrong kind of reference is rejected at deploy time
  rather than producing an alert that silently matches nothing.
</Warning>

### Runs scope

`kind: "runs"` watches your play and tool **runs** end to end, rather than the individual node executions a spans scope sees. A run is one record travelling through a workflow, so `count` counts records processed and `duration` measures a record's whole journey, not one node's.

```ts theme={null}
export const stalledEnrichment = defineAlert("stalled-enrichment", {
  schedule: { type: "cron", cron: "@every 15m" },
  scope: { kind: "runs", workflow: enrich, statuses: ["error"] },
  threshold: { metric: "count", operator: "gte", value: 25 },
  actions: [{ ref: sentinel, config: { prompt: "Investigate {{alert.url}}" } }],
});
```

| Field                       | Narrows to                                                                                                      |
| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `workflow`                  | one play or tool's workflow: a handle, or `workflowRef(uuid)`. Omitted watches every play and tool              |
| `statuses`                  | runs in these statuses (`idle`, `pending`, `running`, `success`, `error`, `cancelling`, `cancelled`, `skipped`) |
| `recordTitleOrErrorMessage` | runs whose record title or error message contains the text (case-insensitive)                                   |
| `releaseUuid`               | runs of one release                                                                                             |
| `userUuid`                  | runs started by one user                                                                                        |

<Note>
  Ad-hoc runs, the ones an agent spawns outside a play or a tool, are never
  counted, whatever the filters. They live on the workspace's default workflow,
  which this source excludes, so an agent's own activity can't drown out the
  workflows you are watching. Use a spans scope with `parentAgent` to alert on
  an agent instead.
</Note>

### Records scope

`kind: "records"` watches the same play and tool work as a runs scope, counted once per **record** instead of once per attempt. Each record is held in its latest state, so a record that failed and was later re-run into success stops counting as failed, and idle or skipped runs never appear at all. Reach for it when you care about how your records are doing rather than how your executions are doing.

```ts theme={null}
export const unresolvedRecords = defineAlert("unresolved-records", {
  schedule: { type: "cron", cron: "@every 1h" },
  scope: { kind: "records", workflow: enrich },
  threshold: { metric: "errorRate", operator: "gte", value: 5 },
  actions: [{ ref: sentinel, config: { prompt: "Records still failing" } }],
});
```

| Field                 | Narrows to                                                                                         |
| --------------------- | -------------------------------------------------------------------------------------------------- |
| `workflow`            | one play or tool's workflow: a handle, or `workflowRef(uuid)`. Omitted watches every play and tool |
| `statuses`            | records in these statuses (`pending`, `running`, `success`, `error`, `cancelling`, `cancelled`)    |
| `titleOrErrorMessage` | records whose title or error message contains the text (case-insensitive)                          |
| `releaseUuid`         | records of one release                                                                             |
| `userUuid`            | records started by one user                                                                        |

<Note>
  Retries are the difference between the two sources. Three failed attempts at
  one record are three failed runs but one failed record, and if a fourth
  attempt succeeds, the record counts as a success while the three failed runs
  remain. Alert on runs to catch a flaky workflow; alert on records to catch
  work that never got done. Ad-hoc runs are excluded here too.
</Note>

### SQL scopes

Two sources run raw SQL and use its result as the value. The query computes the value itself, so the threshold carries only the comparison:

* `kind: "orchestrationQuery"` runs read-only **ClickHouse SQL** over your orchestration data: the `spans`, `runs`, `batches`, and `records` tables, automatically scoped to your workspace.
* `kind: "storageQuery"` runs read-only SQL over your **data warehouse**, referencing models as `<dataset>.<model>` exactly as the model SQL editor does.

```ts theme={null}
export const slowNights = defineAlert("slow-nights", {
  schedule: { type: "cron", cron: "0 * * * *" },
  scope: {
    kind: "orchestrationQuery",
    query: `select count(*) from spans
            where execution_status = 'error'
              and execution_started_at > now() - interval 1 hour`,
  },
  threshold: { operator: "gte", value: 50 },
  actions: [
    { ref: sentinel, config: { prompt: "Error spike: {{event.value}}" } },
  ],
});
```

A warehouse query looks the same, against your own tables:

```ts theme={null}
export const missingEmails = defineAlert("missing-emails", {
  schedule: { type: "cron", cron: "0 * * * *" },
  scope: {
    kind: "storageQuery",
    query: `select 100.0 * sum(case when email is null then 1 else 0 end)
                 / nullif(count(*), 0)
            from crm.contacts`,
  },
  threshold: { operator: "gte", value: 20 },
  actions: [{ ref: sentinel, config: { prompt: "Contact data decayed" } }],
});
```

<Warning>
  Query scopes are **not** windowed for you: Cargo runs the query exactly as
  written. An orchestration query should be self-windowing (as the `interval 1
      hour` above does), otherwise every tick evaluates your whole history. A
  warehouse query sees your models as they stand, which is usually what you
  want: it is a statement about the data, not about a time slice.
</Warning>

The value is the **first column of the first row**, and it must be numeric. A non-number produces an `error` event. A query that returns no rows or a `NULL` counts as an empty window instead: the tick is recorded as `healthy` with `value: null` and nothing fires. That is what an aggregate over no rows gives you, and what a rate query returns for `0 / 0` in an idle window, so an empty window can never quietly read as a real `0` and breach an `lte` threshold.

See [Querying orchestration data](/reference/orchestration-query) for the columns of each orchestration table, the ClickHouse idioms that differ from PostgreSQL, and the limits a query runs under; see [Querying models](/models/querying) for the warehouse side.

<Note>
  A warehouse query never waits for a model to refresh. An alert runs on a cron,
  and blocking a tick on a sync would leave it measuring a moment that has
  passed by the time the sync lands.
</Note>

### Model scope

`kind: "model"` watches the records of one [model](/models/overview), optionally narrowed by a `filter`, the same filter a [segment](/models/segments) is built from. Unlike every other source, a model is measured **as it stands** rather than over the evaluation window:

```ts theme={null}
export const decayingContacts = defineAlert("decaying-contacts", {
  schedule: { type: "cron", cron: "0 9 * * *" },
  scope: {
    kind: "model",
    model: contacts,
    filter: {
      conjonction: "and",
      groups: [
        {
          conjonction: "and",
          conditions: [{ kind: "string", columnSlug: "email", operator: "isNull" }],
        },
      ],
    },
  },
  threshold: { metric: "recordsShare", operator: "gte", value: 30 },
  actions: [{ ref: sentinel, config: { prompt: "{{event.value}}% missing" } }],
});
```

## Threshold: when it breaches

`operator` is `gte` (breach at or above `value`) or `lte` (breach at or below). Apart from the SQL scopes, where the query is the metric, `metric` says what is measured. It is required, since it decides what the value means, and a metric that supports aggregations requires one too.

**Spans, runs and records** share a metric menu; the scope decides what is being counted, one node execution, one record's whole journey, or one record:

| `metric`    | Value                                                            | `aggregation`              |
| ----------- | ---------------------------------------------------------------- | -------------------------- |
| `errorRate` | failed as a percentage (0–100) of the window's **finished** rows | none                       |
| `duration`  | duration in seconds, over finished rows only                     | `avg`, `p50`, `p95`, `p99` |
| `credits`   | credits consumed by the window's rows                            | `sum`, `avg`, `p95`        |
| `count`     | number of spans / runs / records in the window                   | none                       |

<Tip>
  `count` with `lte` is a dead-man's switch: an empty window really evaluates to
  `0`, so **silence breaches**. `{ metric: "count", operator: "lte", value: 0 }`
  tells you a workflow stopped running at all. The other metrics treat an empty
  window as nothing to judge, not as zero — and for `errorRate` and `duration`,
  "empty" means no *finished* rows, so a window of runs that are all still going
  is not judged yet either.
</Tip>

A **model** has its own four, about the records themselves and about how fresh they are:

| `metric`       | Value                                                         |
| -------------- | ------------------------------------------------------------- |
| `recordsCount` | records matching the scope                                    |
| `recordsShare` | matching records as a percentage (0–100) of the model's total |
| `freshness`    | minutes since the model last emitted records                  |
| `syncDuration` | duration in seconds of the model's last finished sync         |

<Note>
  `recordsShare` requires the scope's `filter`: a share of *everything* is
  always 100, so the pair is rejected at save time rather than firing on a
  constant.
</Note>

## Actions: what fires on breach

Each action becomes its own run, exactly like a play's `healthAlertActions`. An action is a connector action, an agent, or a tool, and its `config` is the input it runs with:

```ts theme={null}
actions: [
  { ref: slack.actions.postMessage, config: { channelId: "C0…", body: "…" } },
  { ref: sentinel, config: { prompt: "…" }, waitUntilFinished: true },
  { ref: enrich, config: {} },
]
```

An **agent**'s `config` is typed already — every agent takes the same `{ prompt, output? }`, so a misspelled key is an editor error in the literal above with nothing to import.

A **connector action** or a **tool** has an input of its own, and a bare object literal leaves it unchecked. Wrap it in `alertConnectorAction` / `alertToolAction` to have TypeScript check `config` against the real thing:

```ts theme={null}
import { alertConnectorAction, alertToolAction, defineAlert } from "@cargo-ai/cdk";

actions: [
  alertConnectorAction({
    ref: slack.actions.postMessage,
    config: { channelId: "C0…", body: "Error rate {{event.value}}%" },
  }),
  alertToolAction({ ref: enrich, config: { domain: "acme.com" } }),
]
```

Misspelled and missing fields become editor errors instead of deploy failures, and every field still accepts a `{{ … }}` template string — so a numeric input can be bound to `{{event.value}}`. Where the two differ is the source of the schema: a connector action's comes from [`cargo-ai project types`](/get-started/project-layout), so an integration you haven't synced keeps the loose object, while a tool's comes from its own `defineWorkflow` input and needs no sync — but a `toolRef(uuid)` names a tool you didn't author here, so that one stays loose. Both are helpers rather than the type of `actions` because TypeScript can't infer a per-element type through an array literal, the same reason `agentConnectorTrigger` is one.

`config` is interpolated against the firing under two roots — `alert` is what you configured, `event` is what this firing measured — so an action can say what happened:

| Variable                                              | Value                                       |
| ----------------------------------------------------- | ------------------------------------------- |
| `{{alert.name}}` / `{{alert.uuid}}` / `{{alert.url}}` | the alert that fired                        |
| `{{event.value}}`                                     | the computed value, rounded to two decimals |
| `{{event.threshold}}`                                 | the threshold it was compared against       |
| `{{event.operator}}`                                  | `gte` or `lte`                              |
| `{{event.windowStart}}` / `{{event.windowEnd}}`       | the evaluated window, as ISO timestamps     |
| `{{event.spansUrl}}`                                  | link to the workspace's Spans view          |

## The evaluation window

An alert does **not** re-scan a fixed lookback on every tick. Each evaluation covers the time since the previous one, so windows are contiguous and never overlap and every span is judged exactly once:

* **Window start** — where the last evaluation ended. The very first evaluation starts from the moment the alert was last saved.
* **Window end** — slightly behind now, by an allowance for span indexing lag. Spans that land late are picked up by the next tick instead of being missed.

This is why the cron is the window size: `@every 5m` means each evaluation judges roughly the last five minutes.

The window applies to the **spans**, **runs** and **records** sources. A SQL scope windows itself (or doesn't), and a model scope is a statement about the records as they stand right now; for those two, the cron is only how often the question gets asked.

<Note>
  Actions fire **at most once** per window. Before firing, an alert atomically
  claims its window; if a retry or an overlapping tick already claimed it,
  nothing is recorded and nothing fires. Actions spawn runs that spend credits
  and can take real action, so a duplicate is worse than a rare miss — and a
  sustained breach is detected again on the next tick anyway.
</Note>

Disabled alerts are skipped, and every evaluation — breach or not — records an [event](/alerts/events).

## From the CLI

```bash theme={null}
cargo-ai observability alert list
cargo-ai observability alert get <alert-uuid>

cargo-ai observability alert create \
  --name "Enrich error rate" \
  --cron "@every 5m" \
  --scope '{"kind":"spans","workflowUuid":"<uuid>"}' \
  --threshold '{"metric":"errorRate","operator":"gte","value":10}'

cargo-ai observability alert create \
  --name "Contacts stopped syncing" \
  --cron "0 * * * *" \
  --scope '{"kind":"model","modelUuid":"<uuid>"}' \
  --threshold '{"metric":"freshness","operator":"gte","value":180}'

cargo-ai observability alert update --uuid <alert-uuid> --enabled false
cargo-ai observability alert remove <alert-uuid>
```

`create` also takes `--actions` (a JSON array), `--description` and `--folder`.
On `update`, passing `none` to `--description` or `--folder` clears the field,
while omitting the flag leaves it untouched.

<Note>
  Unlike `defineAlert`, an alert created through the API or the CLI starts
  **disabled** — arm it with `alert update --uuid <uuid> --enabled true` once
  its scope and threshold look right.
</Note>

Try a scope and threshold before you commit to it — `preview` computes the value
now and reports whether it would breach, without firing anything:

```bash theme={null}
cargo-ai observability alert preview \
  --scope '{"kind":"spans","workflowUuid":"<uuid>"}' \
  --threshold '{"metric":"duration","aggregation":"p95","operator":"gte","value":30}' \
  --window-minutes 60
```

`--window-minutes` (default `60`) is the lookback for spans, runs and records
scopes; a query scope windows itself and a model scope is measured as it stands,
so the flag doesn't affect either.

## Using the UI

See [Using the UI](/alerts/using-ui) to build an alert visually, with a live preview of the spans it matches, and [Events](/alerts/events) for reading an alert's history.

An alert built in the UI can be brought back into code: `cargo-ai project pull` writes it as a `defineAlert` under `alerts/`, with its scope, threshold and actions referencing the other resources it was pulled alongside.


# Using UI
Source: https://docs.getcargo.ai/alerts/using-ui

Build an alert visually: pick what it watches with a live preview, set the threshold, and read its firing history.

Alerts have a full editor in the web app, so you can shape a scope against real
data before arming it. Everything here maps one-to-one onto
[`defineAlert`](/alerts/overview), so an alert built in the UI can be moved into
code later (and vice versa).

## The alert list

Open **Alerts** from your workspace sidebar. Each row shows the alert's schedule,
whether it is enabled, its latest evaluation outcome, and who last changed it.

* **New alert** creates an `Untitled` alert — checked hourly, watching every span, breaching at a 10% error rate — and opens it. It starts **disabled**, so nothing fires until you arm it.
* **New folder** groups alerts, the same [folders](/folders/overview) used elsewhere in the workspace. Creating an alert inside a folder files it there.
* Right-click a row (or use its **⋯** menu) to **Edit** its name, description, and folder, **Duplicate** it, **Move to** another folder, or **Remove** it.

<Tip>
  Duplicating is the quickest way to fan one alert out across workflows: the copy
  keeps the original's scope, threshold, schedule, and actions, and starts
  disabled so it can't fire before you have retargeted it.
</Tip>

## Configure the trigger

Open an alert and stay on the **Trigger** tab. The toggle in the header arms and
disarms it, and the name is editable in place.

The data sources are listed under the store they read from: **Orchestration**
(spans, runs, records and SQL) covers what your plays, tools and agents ran,
**Storage** (a model and SQL) covers the data in your models and warehouse.
Picking one shows its description underneath.

The **Scope** section switches on the source you land on:

* **Spans** gives you the same filter bar as the Spans view — workflow or triggering agent, node kind, integration, connector, action, tool, agent, execution status, free-text search — with a live table of the spans currently matching underneath. That table is the fastest way to tell an over-broad scope from an over-narrow one.
* **Runs** gives you the run list's filter bar (play or tool, statuses, release, user, free-text search) with a live table of the matching runs: title and status, credits, the play or tool the run belongs to, and when it was created and finished. On "All triggers" the table spans every play and tool, so the workflow column tells you where each run came from. Ad-hoc runs, the ones agents spawn outside a play or a tool, never appear, because the alert never counts them.
* **Records** gives you the same bar and the same table over records instead of runs: the same work counted once per record, in its latest state, so a record re-run into success stops counting as failed. Its status menu has no idle or skipped, which a record can never be.
* **Orchestration SQL** and **Storage SQL** give you a SQL editor with a preview that runs the query and shows the value it returns, so you can confirm it yields a single number before saving. The [orchestration schema](/reference/orchestration-query) lists the columns of the first; the second runs against your warehouse, where models are referenced as `<dataset>.<model>`. Remember that a query scope [windows itself](/alerts/overview#sql-scopes), or doesn't.
* **Model** pairs a model picker with the usual filter builder, and shows the model's records under it, filtered exactly as the alert measures them, so the rows you see are the ones being counted.

Under the table sits the **preview**, which answers the question the table can't: whether this alert would fire right now, and on what value. It re-evaluates with the table as you change filters, so scope and verdict always describe the same thing. The SQL sources run it from the Preview button in their editor instead, since a half-typed query is not worth running. Windowed sources (spans, runs, records) are read over the last hour, whatever cron you end up setting. A preview that says nothing matched is an answer too: an empty window is never a breach, except for `count` with below-or-equal.

Below the scope, set the **threshold** (metric, aggregation, operator, value), the
**schedule** cron, and the **actions** to fire on breach. Actions accept a
connector action, a tool, or an agent, and their inputs can interpolate the
firing's values — `{{alert.url}}`, `{{event.value}}`, `{{event.spansUrl}}` and
[the rest](/alerts/overview#actions-what-fires-on-breach).

<Warning>
  A spans, runs or records alert's window starts where its last evaluation ended, not at
  a fixed lookback, so the cron is effectively the window size. Widening the
  cron from `@every 5m` to `@every 1h` makes each evaluation judge an hour, which
  changes what a percentage or a percentile actually means. SQL and model scopes
  are not windowed for you, so there the cron is only how often the question
  gets asked.
</Warning>

## Read the history

The **Events** tab lists every evaluation, newest first, with its status, the
value computed, and the window judged. Filter by status to find just the
firings, and expand one to see the runs its actions spawned. See
[Events](/alerts/events) for what each status means.

## Best practices

* **Preview before arming** — shape the scope against the live table, watch the preview under it for the value your threshold would judge, and leave the alert disabled until the numbers look right.
* **Match the cron to the signal** — short windows catch spikes but are noisier; long windows smooth them out and fire later.
* **Watch silence, not just errors** — a `count` / `lte` alert catches a workflow that stopped running, which no error-rate alert can.
* **Make the action say what happened** — interpolate `{{event.value}}` and `{{event.spansUrl}}` so whoever reads the Slack message doesn't have to go hunting.

## Next steps

<CardGroup>
  <Card title="Define alerts in code" icon="code" href="/alerts/overview">
    The `defineAlert` reference — scopes, metrics, actions, and the evaluation
    window.
  </Card>

  <Card title="Read the events" icon="bell" href="/alerts/events">
    Statuses, snapshots, and the runs a firing spawned.
  </Card>

  <Card title="Monitor from the CLI" icon="chart-line" href="/deploy/monitoring">
    Runs, batches, spans, and traces from the terminal.
  </Card>

  <Card title="Play health" icon="play" href="/plays/overview#fallbacks-and-health">
    Batch-health thresholds and alert actions on a play.
  </Card>
</CardGroup>


# Create agent
Source: https://docs.getcargo.ai/api-reference/ai--agents/create-agent

https://api.getcargo.io/openapi.json post /ai/agents
Create a new AI agent (POST /ai/agents).



# Get agent
Source: https://docs.getcargo.ai/api-reference/ai--agents/get-agent

https://api.getcargo.io/openapi.json get /ai/agents/{uuid}
Get an AI agent by UUID (GET /ai/agents/{uuid}).



# List agents
Source: https://docs.getcargo.ai/api-reference/ai--agents/list-agents

https://api.getcargo.io/openapi.json get /ai/agents/list
List all AI agents in the workspace (GET /ai/agents/list).



# Remove agent
Source: https://docs.getcargo.ai/api-reference/ai--agents/remove-agent

https://api.getcargo.io/openapi.json delete /ai/agents/{uuid}
Remove an AI agent (DELETE /ai/agents/{uuid}).



# Update agent
Source: https://docs.getcargo.ai/api-reference/ai--agents/update-agent

https://api.getcargo.io/openapi.json put /ai/agents/{uuid}
Update an AI agent (PUT /ai/agents/{uuid}).



# Close chat
Source: https://docs.getcargo.ai/api-reference/ai--chats/close-chat

https://api.getcargo.io/openapi.json post /ai/chats/{uuid}/close
End a chat session: no further turn, no heartbeat, and no connector or mailbox event wakes it again (POST /ai/chats/{uuid}/close).



# Create chat
Source: https://docs.getcargo.ai/api-reference/ai--chats/create-chat

https://api.getcargo.io/openapi.json post /ai/chats
Create a new chat session (POST /ai/chats).



# Get chat
Source: https://docs.getcargo.ai/api-reference/ai--chats/get-chat

https://api.getcargo.io/openapi.json get /ai/chats/{uuid}
Get a chat session by UUID (GET /ai/chats/{uuid}).



# List chats
Source: https://docs.getcargo.ai/api-reference/ai--chats/list-chats

https://api.getcargo.io/openapi.json get /ai/chats/list
List all chat sessions (GET /ai/chats/list).



# Mint harness proxy token
Source: https://docs.getcargo.ai/api-reference/ai--chats/mint-harness-proxy-token

https://api.getcargo.io/openapi.json post /ai/chats/{uuid}/harness-proxy-token
Mint a temporary Anthropic proxy token for a local Claude Code harness turn. Credit-checks the workspace first. Does not provision a sandbox. (POST /ai/chats/{uuid}/harness-proxy-token).



# Remove chat
Source: https://docs.getcargo.ai/api-reference/ai--chats/remove-chat

https://api.getcargo.io/openapi.json delete /ai/chats/{uuid}
Remove a chat session (DELETE /ai/chats/{uuid}).



# Update chat
Source: https://docs.getcargo.ai/api-reference/ai--chats/update-chat

https://api.getcargo.io/openapi.json put /ai/chats/{uuid}
Update a chat session (PUT /ai/chats/{uuid}).



# Create document
Source: https://docs.getcargo.ai/api-reference/ai--documents/create-document

https://api.getcargo.io/openapi.json post /ai/documents
Create a new AI document (POST /ai/documents).



# Get document
Source: https://docs.getcargo.ai/api-reference/ai--documents/get-document

https://api.getcargo.io/openapi.json get /ai/documents/{uuid}
Get an AI document by UUID (GET /ai/documents/{uuid}).



# List documents
Source: https://docs.getcargo.ai/api-reference/ai--documents/list-documents

https://api.getcargo.io/openapi.json get /ai/documents/list
List all AI documents (GET /ai/documents/list).



# Reset document
Source: https://docs.getcargo.ai/api-reference/ai--documents/reset-document

https://api.getcargo.io/openapi.json post /ai/documents/reset
Reset an AI document (POST /ai/documents/reset).



# Evaluate
Source: https://docs.getcargo.ai/api-reference/ai--evaluator/evaluate

https://api.getcargo.io/openapi.json post /ai/evaluator/evaluate
Run an AI evaluator (POST /ai/evaluator/evaluate).



# Connect MCP client
Source: https://docs.getcargo.ai/api-reference/ai--mcp/connect-mcp-client

https://api.getcargo.io/openapi.json post /ai/mcpClients/connect
Connect to an MCP client (POST /ai/mcpClients/connect).



# Create MCP server
Source: https://docs.getcargo.ai/api-reference/ai--mcp/create-mcp-server

https://api.getcargo.io/openapi.json post /ai/mcpServers
Create a new MCP server (POST /ai/mcpServers).



# Get MCP server
Source: https://docs.getcargo.ai/api-reference/ai--mcp/get-mcp-server

https://api.getcargo.io/openapi.json get /ai/mcpServers/{uuid}
Get an MCP server by UUID (GET /ai/mcpServers/{uuid}).



# List MCP servers
Source: https://docs.getcargo.ai/api-reference/ai--mcp/list-mcp-servers

https://api.getcargo.io/openapi.json get /ai/mcpServers/list
List all MCP servers (GET /ai/mcpServers/list).



# Remove MCP server
Source: https://docs.getcargo.ai/api-reference/ai--mcp/remove-mcp-server

https://api.getcargo.io/openapi.json delete /ai/mcpServers/{uuid}
Remove an MCP server (DELETE /ai/mcpServers/{uuid}).



# Update MCP server
Source: https://docs.getcargo.ai/api-reference/ai--mcp/update-mcp-server

https://api.getcargo.io/openapi.json put /ai/mcpServers/{uuid}
Update an MCP server (PUT /ai/mcpServers/{uuid}).



# List memories
Source: https://docs.getcargo.ai/api-reference/ai--memories/list-memories

https://api.getcargo.io/openapi.json get /ai/memories/list
List all AI memories. Query params: scope (user|agent), agentUuid (required when scope=agent) (GET /ai/memories/list).



# Remove memory
Source: https://docs.getcargo.ai/api-reference/ai--memories/remove-memory

https://api.getcargo.io/openapi.json delete /ai/memories/{mem0Id}
Remove an AI memory. Query params: scope (user|agent), agentUuid (required when scope=agent) (DELETE /ai/memories/{mem0Id}).



# Update memory
Source: https://docs.getcargo.ai/api-reference/ai--memories/update-memory

https://api.getcargo.io/openapi.json put /ai/memories/{mem0Id}
Update an AI memory (PUT /ai/memories/{mem0Id}).



# Cancel messages
Source: https://docs.getcargo.ai/api-reference/ai--messages/cancel-messages

https://api.getcargo.io/openapi.json post /ai/messages/cancel
Cancel messages that have associated Temporal workflows (workflow-backed messages). Skips messages that have no workflow or are already finished. (POST /ai/messages/cancel).



# Create message
Source: https://docs.getcargo.ai/api-reference/ai--messages/create-message

https://api.getcargo.io/openapi.json post /ai/messages
Create a new message in a chat. Returns the user message and a pending assistant message. The assistant response is processed asynchronously. (POST /ai/messages).



# Get message
Source: https://docs.getcargo.ai/api-reference/ai--messages/get-message

https://api.getcargo.io/openapi.json get /ai/messages/{uuid}
Get a message by UUID (GET /ai/messages/{uuid}).



# Ingest local harness messages
Source: https://docs.getcargo.ai/api-reference/ai--messages/ingest-local-harness-messages

https://api.getcargo.io/openapi.json post /ai/messages/ingest
Persist a finished user turn and assistant turn from a local Claude Code harness. Does not start a Temporal workflow or stream. (POST /ai/messages/ingest).



# List messages
Source: https://docs.getcargo.ai/api-reference/ai--messages/list-messages

https://api.getcargo.io/openapi.json get /ai/messages/list
List all messages in a chat (GET /ai/messages/list).



# Remove message
Source: https://docs.getcargo.ai/api-reference/ai--messages/remove-message

https://api.getcargo.io/openapi.json delete /ai/messages/{uuid}
Remove a message from a chat (DELETE /ai/messages/{uuid}).



# Resume message stream
Source: https://docs.getcargo.ai/api-reference/ai--messages/resume-message-stream

https://api.getcargo.io/openapi.json get /ai/messages/resume-stream
Resume streaming a message (GET /ai/messages/resume-stream).



# Stream message
Source: https://docs.getcargo.ai/api-reference/ai--messages/stream-message

https://api.getcargo.io/openapi.json post /ai/messages/stream
Stream a new message in a chat (POST /ai/messages/stream).



# Evaluate prompt
Source: https://docs.getcargo.ai/api-reference/ai--prompts/evaluate-prompt

https://api.getcargo.io/openapi.json post /ai/prompts/evaluate
Evaluate an AI prompt (POST /ai/prompts/evaluate).



# Generate prompt JSON schema
Source: https://docs.getcargo.ai/api-reference/ai--prompts/generate-prompt-json-schema

https://api.getcargo.io/openapi.json post /ai/prompts/generateJsonSchema
Generate a JSON schema for the output of an AI prompt (POST /ai/prompts/generateJsonSchema).



# Optimize prompt
Source: https://docs.getcargo.ai/api-reference/ai--prompts/optimize-prompt

https://api.getcargo.io/openapi.json post /ai/prompts/optimize
Optimize an AI prompt (POST /ai/prompts/optimize).



# Deploy draft release
Source: https://docs.getcargo.ai/api-reference/ai--releases/deploy-draft-release

https://api.getcargo.io/openapi.json post /ai/releases/draft/deploy
Deploy a draft release (POST /ai/releases/draft/deploy).



# Get deployed release
Source: https://docs.getcargo.ai/api-reference/ai--releases/get-deployed-release

https://api.getcargo.io/openapi.json get /ai/releases/deployed
Get the deployed release (GET /ai/releases/deployed).



# Get draft release
Source: https://docs.getcargo.ai/api-reference/ai--releases/get-draft-release

https://api.getcargo.io/openapi.json get /ai/releases/draft
Get the draft release (GET /ai/releases/draft).



# Get release
Source: https://docs.getcargo.ai/api-reference/ai--releases/get-release

https://api.getcargo.io/openapi.json get /ai/releases/{uuid}
Get a release by UUID (GET /ai/releases/{uuid}).



# List releases
Source: https://docs.getcargo.ai/api-reference/ai--releases/list-releases

https://api.getcargo.io/openapi.json get /ai/releases/list
List all releases (GET /ai/releases/list).



# Update draft release
Source: https://docs.getcargo.ai/api-reference/ai--releases/update-draft-release

https://api.getcargo.io/openapi.json put /ai/releases/draft/update
Update the draft release (PUT /ai/releases/draft/update).



# Generate suggested actions
Source: https://docs.getcargo.ai/api-reference/ai--suggested-actions/generate-suggested-actions

https://api.getcargo.io/openapi.json post /ai/suggestedActions/generate
Generate suggested actions for a chat (POST /ai/suggestedActions/generate).



# Get template
Source: https://docs.getcargo.ai/api-reference/ai--templates/get-template

https://api.getcargo.io/openapi.json get /ai/templates/{slug}
Get an AI template by slug (GET /ai/templates/{slug}).



# Get template documentation
Source: https://docs.getcargo.ai/api-reference/ai--templates/get-template-documentation

https://api.getcargo.io/openapi.json get /ai/templates/{slug}/documentation
Get the documentation for an AI template (GET /ai/templates/{slug}/documentation).



# List templates
Source: https://docs.getcargo.ai/api-reference/ai--templates/list-templates

https://api.getcargo.io/openapi.json post /ai/templates/list
List all AI templates (POST /ai/templates/list).



# List votes
Source: https://docs.getcargo.ai/api-reference/ai--votes/list-votes

https://api.getcargo.io/openapi.json get /ai/votes/list
List all votes (GET /ai/votes/list).



# Upsert vote
Source: https://docs.getcargo.ai/api-reference/ai--votes/upsert-vote

https://api.getcargo.io/openapi.json put /ai/votes
Create or update a vote (PUT /ai/votes).



# Authentication
Source: https://docs.getcargo.ai/api-reference/authentication

How to sign in with the CLI, pass a bearer token to the REST API, and discover OAuth metadata.

There is **one credential**. The CLI holds it, and everything reads it: the REST API, your project, the skills, and the MCP bridge. Sign in once and nothing else needs configuring.

```sh theme={null}
npm install -g @cargo-ai/cli
cargo-ai login --email you@company.com
```

A new account starts with 100 free credits and needs no card. `--email` mails a one-time code and creates the account and a workspace on first use.

## Methods

| You are                            | Use                                                   | Browser |
| ---------------------------------- | ----------------------------------------------------- | ------- |
| An agent, a sandbox, CI, any shell | `cargo-ai login --email you@company.com`              | no      |
| A person at a workstation          | `cargo-ai login --oauth`                              | yes     |
| CI with a token already issued     | `cargo-ai login --token <token>` or `CARGO_API_TOKEN` | no      |

In an agent or sandbox shell with no terminal to prompt at, the first `--email` call sends the code and exits. Re-run it with `--code`.

## Calling the API

```bash theme={null}
curl https://api.getcargo.io/v1/storage/models/list \
  -H "Authorization: Bearer $CARGO_API_TOKEN"
```

See [API Reference](/api-reference/introduction) for the rest of the surface.

## OAuth

Authorization-server metadata (RFC 8414): [https://auth.getcargo.io/.well-known/oauth-authorization-server](https://auth.getcargo.io/.well-known/oauth-authorization-server). Device code, authorization code with PKCE (S256), registration, and revocation.

The product MCP server at `https://mcp.getcargo.io` challenges with OAuth. See [MCP servers](/mcp-servers/overview).

## Machine-readable walkthrough

The WorkOS `auth.md` walkthrough — Discover, Pick a method, Register, Claim, Use, Revocation — is [https://www.getcargo.ai/auth.md](https://www.getcargo.ai/auth.md).


# Create payment method portal session
Source: https://docs.getcargo.ai/api-reference/billing--subscription/create-payment-method-portal-session

https://api.getcargo.io/openapi.json post /billing/subscriptions/paymentMethodPortalSessions
Create a Stripe portal session that opens directly on the card form (POST /billing/subscriptions/paymentMethodPortalSessions).



# Create portal session
Source: https://docs.getcargo.ai/api-reference/billing--subscription/create-portal-session

https://api.getcargo.io/openapi.json post /billing/subscriptions/portalSessions
Create a Stripe customer portal session (POST /billing/subscriptions/portalSessions).



# Create setup intent
Source: https://docs.getcargo.ai/api-reference/billing--subscription/create-setup-intent

https://api.getcargo.io/openapi.json post /billing/subscriptions/setupIntent
Create a Stripe setup intent for adding payment method (POST /billing/subscriptions/setupIntent).



# Get credit card
Source: https://docs.getcargo.ai/api-reference/billing--subscription/get-credit-card

https://api.getcargo.io/openapi.json get /billing/subscriptions/creditCard
Get the credit card on file (GET /billing/subscriptions/creditCard).



# Get invoices
Source: https://docs.getcargo.ai/api-reference/billing--subscription/get-invoices

https://api.getcargo.io/openapi.json get /billing/subscriptions/invoices
Get subscription invoices (GET /billing/subscriptions/invoices).



# Get Stripe publishable key
Source: https://docs.getcargo.ai/api-reference/billing--subscription/get-stripe-publishable-key

https://api.getcargo.io/openapi.json get /billing/subscriptions/stripePublishableKey
Get the Stripe publishable key for tokenizing a card (GET /billing/subscriptions/stripePublishableKey).



# Get subscription
Source: https://docs.getcargo.ai/api-reference/billing--subscription/get-subscription

https://api.getcargo.io/openapi.json get /billing/subscriptions
Get the current workspace subscription (GET /billing/subscriptions).



# Update credits overage behaviors
Source: https://docs.getcargo.ai/api-reference/billing--subscription/update-credits-overage-behaviors

https://api.getcargo.io/openapi.json put /billing/subscriptions/creditsOverageBehaviors
Update the credits overage behaviors settings (PUT /billing/subscriptions/creditsOverageBehaviors).



# Update payment method
Source: https://docs.getcargo.ai/api-reference/billing--subscription/update-payment-method

https://api.getcargo.io/openapi.json put /billing/subscriptions/paymentMethod
Update the payment method on file (PUT /billing/subscriptions/paymentMethod).



# Update plan
Source: https://docs.getcargo.ai/api-reference/billing--subscription/update-plan

https://api.getcargo.io/openapi.json put /billing/subscriptions/plan
Update the subscription plan (PUT /billing/subscriptions/plan).



# Update topup
Source: https://docs.getcargo.ai/api-reference/billing--subscription/update-topup

https://api.getcargo.io/openapi.json put /billing/subscriptions/topup
Update the automatic topup settings (PUT /billing/subscriptions/topup).



# Get usage metrics
Source: https://docs.getcargo.ai/api-reference/billing--usage/get-usage-metrics

https://api.getcargo.io/openapi.json get /billing/usage/metrics
Get usage metrics for the workspace (GET /billing/usage/metrics).



# Autocomplete connectors
Source: https://docs.getcargo.ai/api-reference/connection--connectors/autocomplete-connectors

https://api.getcargo.io/openapi.json post /connection/connectors/{uuid}/autocomplete
Get connector autocomplete suggestions (POST /connection/connectors/{uuid}/autocomplete).



# Check connector exists by slug
Source: https://docs.getcargo.ai/api-reference/connection--connectors/check-connector-exists-by-slug

https://api.getcargo.io/openapi.json get /connection/connectors/existsBySlug
Check if a connector exists by its slug (GET /connection/connectors/existsBySlug).



# Create connector
Source: https://docs.getcargo.ai/api-reference/connection--connectors/create-connector

https://api.getcargo.io/openapi.json post /connection/connectors
Create a new connector (POST /connection/connectors).



# Get connector
Source: https://docs.getcargo.ai/api-reference/connection--connectors/get-connector

https://api.getcargo.io/openapi.json get /connection/connectors/{uuid}
Get a connector by UUID (GET /connection/connectors/{uuid}).



# Get dynamic schema
Source: https://docs.getcargo.ai/api-reference/connection--connectors/get-dynamic-schema

https://api.getcargo.io/openapi.json post /connection/connectors/{uuid}/dynamicSchemas/{slug}
Get dynamic schema for a connector (POST /connection/connectors/{uuid}/dynamicSchemas/{slug}).



# Get language models
Source: https://docs.getcargo.ai/api-reference/connection--connectors/get-language-models

https://api.getcargo.io/openapi.json get /connection/connectors/{uuid}/languageModels
Get the language models available for a connector (GET /connection/connectors/{uuid}/languageModels).



# List connectors
Source: https://docs.getcargo.ai/api-reference/connection--connectors/list-connectors

https://api.getcargo.io/openapi.json get /connection/connectors/list
List all connectors in the workspace (GET /connection/connectors/list).



# Remove connector
Source: https://docs.getcargo.ai/api-reference/connection--connectors/remove-connector

https://api.getcargo.io/openapi.json delete /connection/connectors/{uuid}
Remove a connector (DELETE /connection/connectors/{uuid}).



# Update connector
Source: https://docs.getcargo.ai/api-reference/connection--connectors/update-connector

https://api.getcargo.io/openapi.json put /connection/connectors/{uuid}
Update a connector (PUT /connection/connectors/{uuid}).



# Create custom integration
Source: https://docs.getcargo.ai/api-reference/connection--custom-integrations/create-custom-integration

https://api.getcargo.io/openapi.json post /connection/customIntegrations
Create a new custom integration (POST /connection/customIntegrations).



# Get custom integration
Source: https://docs.getcargo.ai/api-reference/connection--custom-integrations/get-custom-integration

https://api.getcargo.io/openapi.json get /connection/customIntegrations/{uuid}
Get a custom integration by UUID (GET /connection/customIntegrations/{uuid}).



# List custom integrations
Source: https://docs.getcargo.ai/api-reference/connection--custom-integrations/list-custom-integrations

https://api.getcargo.io/openapi.json get /connection/customIntegrations/list
List all custom integrations (GET /connection/customIntegrations/list).



# Remove custom integration
Source: https://docs.getcargo.ai/api-reference/connection--custom-integrations/remove-custom-integration

https://api.getcargo.io/openapi.json delete /connection/customIntegrations/{uuid}
Remove a custom integration (DELETE /connection/customIntegrations/{uuid}).



# Update custom integration
Source: https://docs.getcargo.ai/api-reference/connection--custom-integrations/update-custom-integration

https://api.getcargo.io/openapi.json put /connection/customIntegrations/{uuid}
Update a custom integration (PUT /connection/customIntegrations/{uuid}).



# Complete OAuth
Source: https://docs.getcargo.ai/api-reference/connection--integrations/complete-oauth

https://api.getcargo.io/openapi.json post /connection/integrations/{slug}/completeOauth
Complete OAuth flow for an integration (POST /connection/integrations/{slug}/completeOauth).



# Get integration
Source: https://docs.getcargo.ai/api-reference/connection--integrations/get-integration

https://api.getcargo.io/openapi.json get /connection/integrations/{slug}
Get an integration by slug (GET /connection/integrations/{slug}).



# Get integration documentation
Source: https://docs.getcargo.ai/api-reference/connection--integrations/get-integration-documentation

https://api.getcargo.io/openapi.json get /connection/integrations/{slug}/documentation
Get the documentation for an integration (GET /connection/integrations/{slug}/documentation).



# Initiate OAuth
Source: https://docs.getcargo.ai/api-reference/connection--integrations/initiate-oauth

https://api.getcargo.io/openapi.json post /connection/integrations/{slug}/initiateOauth
Initiate the OAuth flow for an integration and return a consent URL. (POST /connection/integrations/{slug}/initiateOauth).



# List integrations
Source: https://docs.getcargo.ai/api-reference/connection--integrations/list-integrations

https://api.getcargo.io/openapi.json get /connection/integrations/list
List all available integrations (GET /connection/integrations/list).



# Get native integration
Source: https://docs.getcargo.ai/api-reference/connection--native-integrations/get-native-integration

https://api.getcargo.io/openapi.json get /connection/nativeIntegrations
Get the native integration (GET /connection/nativeIntegrations).



# Get file
Source: https://docs.getcargo.ai/api-reference/content--files/get-file

https://api.getcargo.io/openapi.json get /content/files/{uuid}
Get a workspace file by UUID (GET /content/files/{uuid}).



# Get file bytes
Source: https://docs.getcargo.ai/api-reference/content--files/get-file-bytes

https://api.getcargo.io/openapi.json get /content/files/{uuid}/raw
Stream a workspace file's raw bytes for inline preview (capped at 10 MB) (GET /content/files/{uuid}/raw).



# List files
Source: https://docs.getcargo.ai/api-reference/content--files/list-files

https://api.getcargo.io/openapi.json get /content/files/list
List workspace files (GET /content/files/list).



# Remove file
Source: https://docs.getcargo.ai/api-reference/content--files/remove-file

https://api.getcargo.io/openapi.json delete /content/files/{uuid}
Remove a workspace file (DELETE /content/files/{uuid}).



# Update file
Source: https://docs.getcargo.ai/api-reference/content--files/update-file

https://api.getcargo.io/openapi.json put /content/files/{uuid}
Update a workspace file (PUT /content/files/{uuid}).



# Upload file
Source: https://docs.getcargo.ai/api-reference/content--files/upload-file

https://api.getcargo.io/openapi.json post /content/files/upload
Upload a workspace file for RAG and agent resources (POST /content/files/upload).



# Create library
Source: https://docs.getcargo.ai/api-reference/content--libraries/create-library

https://api.getcargo.io/openapi.json post /content/libraries/create
Create a connector file library (POST /content/libraries/create).



# Get library
Source: https://docs.getcargo.ai/api-reference/content--libraries/get-library

https://api.getcargo.io/openapi.json get /content/libraries/{uuid}
Get a workspace library by UUID (GET /content/libraries/{uuid}).



# List libraries
Source: https://docs.getcargo.ai/api-reference/content--libraries/list-libraries

https://api.getcargo.io/openapi.json get /content/libraries/list
List workspace libraries (GET /content/libraries/list).



# Remove library
Source: https://docs.getcargo.ai/api-reference/content--libraries/remove-library

https://api.getcargo.io/openapi.json delete /content/libraries/{uuid}
Remove a workspace library (DELETE /content/libraries/{uuid}).



# Update library
Source: https://docs.getcargo.ai/api-reference/content--libraries/update-library

https://api.getcargo.io/openapi.json patch /content/libraries/{uuid}
Update a workspace library (PATCH /content/libraries/{uuid}).



# Get context graph
Source: https://docs.getcargo.ai/api-reference/context--graph/get-context-graph

https://api.getcargo.io/openapi.json get /context/graph
Get the knowledge graph of the workspace context repository: nodes for markdown files and edges for links between them. (GET /context/graph).



# Get context repository
Source: https://docs.getcargo.ai/api-reference/context--repository/get-context-repository

https://api.getcargo.io/openapi.json get /context/repository
Get the context repository configuration for the current workspace. (GET /context/repository).



# Browse runtime sandbox
Source: https://docs.getcargo.ai/api-reference/context--runtime/browse-runtime-sandbox

https://api.getcargo.io/openapi.json get /context/runtime
List entries at a path in the workspace runtime sandbox. Omit `path` to list the root, or pass `depth=-1` (with no `path`) to fetch the entire repository tree from the configured default branch on GitHub in one call. (GET /context/runtime).



# Edit runtime sandbox file
Source: https://docs.getcargo.ai/api-reference/context--runtime/edit-runtime-sandbox-file

https://api.getcargo.io/openapi.json patch /context/runtime/content
Replace occurrences of `oldString` with `newString` in a file in the workspace runtime sandbox, then push the change to the workspace's default branch on GitHub. By default `oldString` must occur exactly once; pass `replaceAll: true` to replace every occurrence. (PATCH /context/runtime/content).



# Execute in runtime sandbox
Source: https://docs.getcargo.ai/api-reference/context--runtime/execute-in-runtime-sandbox

https://api.getcargo.io/openapi.json post /context/runtime/execute
Run a shell command in the workspace runtime sandbox. Tracked working-tree changes the command produced (additions, edits, deletions, renames) are auto-committed and pushed to the workspace's default branch as a single commit. Pass `commitMessage` to customize the commit subject; gitignored paths are skipped. The response's `commit` field is present iff a commit landed. (POST /context/runtime/execute).



# Read runtime sandbox file
Source: https://docs.getcargo.ai/api-reference/context--runtime/read-runtime-sandbox-file

https://api.getcargo.io/openapi.json post /context/runtime/content
Read a UTF-8 file from the workspace runtime sandbox. Returns the file content. (POST /context/runtime/content).



# Read runtime sandbox file as raw bytes
Source: https://docs.getcargo.ai/api-reference/context--runtime/read-runtime-sandbox-file-as-raw-bytes

https://api.getcargo.io/openapi.json get /context/runtime/raw
Stream the raw bytes of a file from the workspace context repository's default branch on GitHub, with a resolved `Content-Type` header. Used by the file viewer for binary previews (images, PDFs). (GET /context/runtime/raw).



# Write runtime sandbox file
Source: https://docs.getcargo.ai/api-reference/context--runtime/write-runtime-sandbox-file

https://api.getcargo.io/openapi.json put /context/runtime/content
Create or overwrite a file in the workspace runtime sandbox and push the change to the workspace's default branch on GitHub. (PUT /context/runtime/content).



# Cancel domain
Source: https://docs.getcargo.ai/api-reference/domain-management--domains/cancel-domain

https://api.getcargo.io/openapi.json delete /domainManagement/domains/{uuid}
Cancel a managed domain; credits are not refunded (DELETE /domainManagement/domains/{uuid}).



# Connect domain
Source: https://docs.getcargo.ai/api-reference/domain-management--domains/connect-domain

https://api.getcargo.io/openapi.json post /domainManagement/domains/connect
Connect a domain the workspace already owns elsewhere; free, and pending until its ownership record is published (POST /domainManagement/domains/connect).



# Get domain
Source: https://docs.getcargo.ai/api-reference/domain-management--domains/get-domain

https://api.getcargo.io/openapi.json get /domainManagement/domains/{uuid}
Get a managed domain by UUID (GET /domainManagement/domains/{uuid}).



# Get domain suggestions
Source: https://docs.getcargo.ai/api-reference/domain-management--domains/get-domain-suggestions

https://api.getcargo.io/openapi.json get /domainManagement/domains/suggestions
Get purchasable alternative domain names for a search (GET /domainManagement/domains/suggestions).



# List domains
Source: https://docs.getcargo.ai/api-reference/domain-management--domains/list-domains

https://api.getcargo.io/openapi.json get /domainManagement/domains
List the workspace's managed domains (GET /domainManagement/domains).



# Purchase domain
Source: https://docs.getcargo.ai/api-reference/domain-management--domains/purchase-domain

https://api.getcargo.io/openapi.json post /domainManagement/domains
Purchase a domain; charged in workspace credits (POST /domainManagement/domains).



# Refresh domain status
Source: https://docs.getcargo.ai/api-reference/domain-management--domains/refresh-domain-status

https://api.getcargo.io/openapi.json post /domainManagement/domains/{uuid}/refresh-status
Re-poll the registrar for a managed domain's status (POST /domainManagement/domains/{uuid}/refresh-status).



# Search domain
Source: https://docs.getcargo.ai/api-reference/domain-management--domains/search-domain

https://api.getcargo.io/openapi.json get /domainManagement/domains/search
Check a domain name's availability and price in credits (exact match) (GET /domainManagement/domains/search).



# Update domain
Source: https://docs.getcargo.ai/api-reference/domain-management--domains/update-domain

https://api.getcargo.io/openapi.json put /domainManagement/domains/{uuid}
Update a managed domain's DNS zone, apex redirect, or DMARC. Refused for a connected domain, whose zone lives at the workspace's own DNS provider. (PUT /domainManagement/domains/{uuid}).



# Evaluate expression
Source: https://docs.getcargo.ai/api-reference/expression--expressions/evaluate-expression

https://api.getcargo.io/openapi.json post /expression/expressions/evaluate
Evaluate a formula expression (POST /expression/expressions/evaluate).



# Generate expression
Source: https://docs.getcargo.ai/api-reference/expression--expressions/generate-expression

https://api.getcargo.io/openapi.json post /expression/expressions/generate
Generate an expression using AI (POST /expression/expressions/generate).



# Create favorite recipe
Source: https://docs.getcargo.ai/api-reference/expression--favorite-recipes/create-favorite-recipe

https://api.getcargo.io/openapi.json post /expression/favoriteRecipes
Add a recipe to favorites (POST /expression/favoriteRecipes).



# Remove favorite recipe
Source: https://docs.getcargo.ai/api-reference/expression--favorite-recipes/remove-favorite-recipe

https://api.getcargo.io/openapi.json delete /expression/favoriteRecipes/{recipeUuid}
Remove a recipe from favorites (DELETE /expression/favoriteRecipes/{recipeUuid}).



# Archive recipe
Source: https://docs.getcargo.ai/api-reference/expression--recipes/archive-recipe

https://api.getcargo.io/openapi.json put /expression/recipes/{uuid}/archive
Archive an expression recipe (PUT /expression/recipes/{uuid}/archive).



# Create new version
Source: https://docs.getcargo.ai/api-reference/expression--recipes/create-new-version

https://api.getcargo.io/openapi.json post /expression/recipes/{uuid}
Create a new version of a recipe (POST /expression/recipes/{uuid}).



# Create recipe
Source: https://docs.getcargo.ai/api-reference/expression--recipes/create-recipe

https://api.getcargo.io/openapi.json post /expression/recipes
Create a new expression recipe (POST /expression/recipes).



# Get last version
Source: https://docs.getcargo.ai/api-reference/expression--recipes/get-last-version

https://api.getcargo.io/openapi.json get /expression/recipes/{uuidOrShortId}/last
Get the last version of a recipe (GET /expression/recipes/{uuidOrShortId}/last).



# Get recipe
Source: https://docs.getcargo.ai/api-reference/expression--recipes/get-recipe

https://api.getcargo.io/openapi.json get /expression/recipes/{uuidOrShortId}/{version}
Get a recipe by UUID or short ID and version (GET /expression/recipes/{uuidOrShortId}/{version}).



# List recipes
Source: https://docs.getcargo.ai/api-reference/expression--recipes/list-recipes

https://api.getcargo.io/openapi.json get /expression/recipes/list
List all expression recipes (GET /expression/recipes/list).



# Count analytics events
Source: https://docs.getcargo.ai/api-reference/hosting--analytics/count-analytics-events

https://api.getcargo.io/openapi.json post /hosting/analytics/count
Count analytics events captured for a hosted app (POST /hosting/analytics/count).



# List analytics events
Source: https://docs.getcargo.ai/api-reference/hosting--analytics/list-analytics-events

https://api.getcargo.io/openapi.json post /hosting/analytics/list
List analytics events captured for a hosted app (POST /hosting/analytics/list).



# Create app
Source: https://docs.getcargo.ai/api-reference/hosting--apps/create-app

https://api.getcargo.io/openapi.json post /hosting/apps
Create a new hosted app (POST /hosting/apps).



# Get app
Source: https://docs.getcargo.ai/api-reference/hosting--apps/get-app

https://api.getcargo.io/openapi.json get /hosting/apps/{uuid}
Get a hosted app by UUID (GET /hosting/apps/{uuid}).



# List apps
Source: https://docs.getcargo.ai/api-reference/hosting--apps/list-apps

https://api.getcargo.io/openapi.json post /hosting/apps/list
List hosted apps in the workspace (POST /hosting/apps/list).



# Remove app
Source: https://docs.getcargo.ai/api-reference/hosting--apps/remove-app

https://api.getcargo.io/openapi.json delete /hosting/apps/{uuid}
Remove a hosted app (DELETE /hosting/apps/{uuid}).



# Update app
Source: https://docs.getcargo.ai/api-reference/hosting--apps/update-app

https://api.getcargo.io/openapi.json put /hosting/apps/{uuid}
Update a hosted app (PUT /hosting/apps/{uuid}).



# Attach custom domain
Source: https://docs.getcargo.ai/api-reference/hosting--custom-domains/attach-custom-domain

https://api.getcargo.io/openapi.json post /hosting/custom-domains
Attach a custom domain to an app or worker (POST /hosting/custom-domains).



# Detach custom domain
Source: https://docs.getcargo.ai/api-reference/hosting--custom-domains/detach-custom-domain

https://api.getcargo.io/openapi.json delete /hosting/custom-domains/{uuid}
Detach a custom domain from an app or worker (DELETE /hosting/custom-domains/{uuid}).



# Get custom domain
Source: https://docs.getcargo.ai/api-reference/hosting--custom-domains/get-custom-domain

https://api.getcargo.io/openapi.json get /hosting/custom-domains/{uuid}
Get a custom domain by UUID (GET /hosting/custom-domains/{uuid}).



# List custom domains
Source: https://docs.getcargo.ai/api-reference/hosting--custom-domains/list-custom-domains

https://api.getcargo.io/openapi.json get /hosting/custom-domains/list
List custom domains attached to an app or worker (GET /hosting/custom-domains/list).



# Refresh custom domain status
Source: https://docs.getcargo.ai/api-reference/hosting--custom-domains/refresh-custom-domain-status

https://api.getcargo.io/openapi.json post /hosting/custom-domains/{uuid}/refresh-status
Re-poll the provider for a custom domain's status (POST /hosting/custom-domains/{uuid}/refresh-status).



# Cancel deployment
Source: https://docs.getcargo.ai/api-reference/hosting--deployments/cancel-deployment

https://api.getcargo.io/openapi.json post /hosting/deployments/cancel
Cancel an in-progress deployment (POST /hosting/deployments/cancel).



# Count deployments
Source: https://docs.getcargo.ai/api-reference/hosting--deployments/count-deployments

https://api.getcargo.io/openapi.json post /hosting/deployments/count
Count deployments for an app or worker (POST /hosting/deployments/count).



# Create deployment
Source: https://docs.getcargo.ai/api-reference/hosting--deployments/create-deployment

https://api.getcargo.io/openapi.json post /hosting/deployments
Create a new deployment for an app or worker (POST /hosting/deployments).



# Get deployment
Source: https://docs.getcargo.ai/api-reference/hosting--deployments/get-deployment

https://api.getcargo.io/openapi.json get /hosting/deployments/{uuid}
Get a deployment by UUID (GET /hosting/deployments/{uuid}).



# Get deployment build log URL
Source: https://docs.getcargo.ai/api-reference/hosting--deployments/get-deployment-build-log-url

https://api.getcargo.io/openapi.json get /hosting/deployments/{uuid}/build-log-url
Get a signed URL to download a deployment's build log (GET /hosting/deployments/{uuid}/build-log-url).



# Get deployment source archive URL
Source: https://docs.getcargo.ai/api-reference/hosting--deployments/get-deployment-source-archive-url

https://api.getcargo.io/openapi.json get /hosting/deployments/{uuid}/source-archive-url
Get a signed URL to download a deployment's source archive (GET /hosting/deployments/{uuid}/source-archive-url).



# Get promoted deployment
Source: https://docs.getcargo.ai/api-reference/hosting--deployments/get-promoted-deployment

https://api.getcargo.io/openapi.json get /hosting/deployments/promoted
Get the currently promoted deployment for an app or worker (GET /hosting/deployments/promoted).



# List deployments
Source: https://docs.getcargo.ai/api-reference/hosting--deployments/list-deployments

https://api.getcargo.io/openapi.json post /hosting/deployments/list
List deployments for an app or worker (POST /hosting/deployments/list).



# Promote deployment
Source: https://docs.getcargo.ai/api-reference/hosting--deployments/promote-deployment

https://api.getcargo.io/openapi.json post /hosting/deployments/promote
Promote a deployment to serve live traffic (POST /hosting/deployments/promote).



# Create env var
Source: https://docs.getcargo.ai/api-reference/hosting--env-vars/create-env-var

https://api.getcargo.io/openapi.json post /hosting/env-vars
Create an environment variable for an app or worker (POST /hosting/env-vars).



# List env vars
Source: https://docs.getcargo.ai/api-reference/hosting--env-vars/list-env-vars

https://api.getcargo.io/openapi.json get /hosting/env-vars
List environment variables for an app or worker (GET /hosting/env-vars).



# Remove env var
Source: https://docs.getcargo.ai/api-reference/hosting--env-vars/remove-env-var

https://api.getcargo.io/openapi.json delete /hosting/env-vars/{uuid}
Remove an environment variable (DELETE /hosting/env-vars/{uuid}).



# Update env var
Source: https://docs.getcargo.ai/api-reference/hosting--env-vars/update-env-var

https://api.getcargo.io/openapi.json patch /hosting/env-vars/{uuid}
Update an environment variable (PATCH /hosting/env-vars/{uuid}).



# Count logs
Source: https://docs.getcargo.ai/api-reference/hosting--logs/count-logs

https://api.getcargo.io/openapi.json post /hosting/logs/count
Count runtime logs for a hosted worker (POST /hosting/logs/count).



# List logs
Source: https://docs.getcargo.ai/api-reference/hosting--logs/list-logs

https://api.getcargo.io/openapi.json post /hosting/logs/list
List runtime logs for a hosted worker (POST /hosting/logs/list).



# Create worker
Source: https://docs.getcargo.ai/api-reference/hosting--workers/create-worker

https://api.getcargo.io/openapi.json post /hosting/workers
Create a new hosted worker (POST /hosting/workers).



# Get worker
Source: https://docs.getcargo.ai/api-reference/hosting--workers/get-worker

https://api.getcargo.io/openapi.json get /hosting/workers/{uuid}
Get a hosted worker by UUID (GET /hosting/workers/{uuid}).



# List workers
Source: https://docs.getcargo.ai/api-reference/hosting--workers/list-workers

https://api.getcargo.io/openapi.json post /hosting/workers/list
List hosted workers in the workspace (POST /hosting/workers/list).



# Remove worker
Source: https://docs.getcargo.ai/api-reference/hosting--workers/remove-worker

https://api.getcargo.io/openapi.json delete /hosting/workers/{uuid}
Remove a hosted worker (DELETE /hosting/workers/{uuid}).



# Update worker
Source: https://docs.getcargo.ai/api-reference/hosting--workers/update-worker

https://api.getcargo.io/openapi.json put /hosting/workers/{uuid}
Update a hosted worker (PUT /hosting/workers/{uuid}).



# API Reference
Source: https://docs.getcargo.ai/api-reference/introduction

Complete reference for the Cargo REST API

The Cargo API allows you to programmatically interact with the Cargo platform. Use it to manage your data models, orchestrate workflows, build AI agents, and integrate with your existing systems.

For JavaScript and TypeScript, you can use our official client library [@cargo-ai/api](https://www.npmjs.com/package/@cargo-ai/api) for a typed, convenient way to call the API.

## Platform Overview

Cargo is built around eight core domains that work together to automate your go-to-market operations:

```mermaid theme={null}
flowchart LR
    subgraph Storage["Storage"]
        Dataset["Dataset"]
        Model["Model"]
        Dataset --> Model
    end

    subgraph Segmentation["Segmentation"]
        Segment["Segment"]
        Change["Change"]
        Segment --> Change
    end

    subgraph Connections["Connection"]
        Connector["Connector"]
        Action["Action"]
        Extractor["Extractor"]
        Connector --> Action
        Connector --> Extractor
    end

    subgraph Content["Content"]
        File["File"]
        Library["Library"]
    end

    subgraph Context["Context"]
        Repository["Repository"]
        Graph["Knowledge Graph"]
        Repository --> Graph
    end

    subgraph Orchestration["Orchestration"]
        Tool["Tool"]
        Play["Play"]
        Workflow["Workflow"]
        Tool --> Workflow
        Play --> Workflow
    end

    subgraph AI["AI"]
        Agent["Agent"]
    end

    subgraph Hosting["Hosting"]
        Deployment["Deployment"]
        App["App"]
        Worker["Worker"]
        Deployment --> App
        Deployment --> Worker
    end

    Extractor -->|"syncs to"| Model
    Connector -->|"backs"| Library
    Model -->|"filters into"| Segment
    Change -->|"triggers"| Play
    Action -->|"sequenced in"| Workflow
    Action -->|"available in"| Agent
    Play -->|"orchestrates"| Tool
    Agent -->|"uses"| Tool
    Agent -->|"searches"| Model
    Agent -->|"searches"| File
    Agent -->|"searches"| Library
    Agent -->|"references"| Graph
```

### Core Entities

| Entity              | Description                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Dataset**         | A collection of Models. Organizes your data into logical groups.                                                   |
| **Model**           | Structured tables (Companies, Contacts, etc.) that store your data.                                                |
| **Connector**       | An authenticated connection to an external service (HubSpot, Salesforce, etc.).                                    |
| **Extractor**       | Syncs data from a Connector into a Model.                                                                          |
| **Action**          | Operations provided by Connectors (enrich, write to CRM, send email, etc.). Available in Tools, Plays, and Agents. |
| **Segment**         | A filtered subset of a Model's records.                                                                            |
| **Change**          | Records entering or exiting a Segment. Used to trigger Plays.                                                      |
| **Tool**            | Reusable automation units. Can be triggered manually, via API, or used by Agents and Plays.                        |
| **Workflow**        | The step-by-step automation logic within a Tool or Play. Defines the sequence of Actions to execute.               |
| **Play**            | Event-driven automations that trigger on Changes. Orchestrate Tools and Actions.                                   |
| **Agent**           | AI-powered workers that use reasoning to execute tasks. Can call Tools, use Actions, and search Models.            |
| **File**            | Documents uploaded for Agents to search and reference.                                                             |
| **Library**         | A native or connector-backed collection of documents, indexed for Agent retrieval (RAG).                           |
| **Repository**      | A git-backed store of markdown/MDX GTM context for the workspace.                                                  |
| **Knowledge Graph** | The relationship graph built from the Context repository, giving Agents structured GTM context.                    |
| **App**             | A hosted Vite SPA served on `*.cargo.app` that reads workspace data via the Cargo API.                             |
| **Worker**          | A serverless edge HTTP handler that runs custom logic against the Cargo API.                                       |
| **Deployment**      | A shipped and promoted version of a hosted App or Worker.                                                          |

## Base URL

All API requests should be made to:

```
https://api.getcargo.io/v1
```

## Authentication

The Cargo API uses Bearer token authentication. Include your API token in the `Authorization` header of all requests:

```bash theme={null}
curl -X GET "https://api.getcargo.io/v1/storage/models/list" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### Getting your API Token

1. Navigate to your workspace settings
2. Go to **Settings** > **API Tokens**
3. Click **Create Token** and copy the generated token

<Warning>
  Keep your API token secure. Never share it publicly or commit it to version
  control.
</Warning>

## Response Format

All API responses are returned in JSON format. Data is returned directly at the root level.

### Success Response

```json theme={null}
{
  "models": [...]
}
```

### Error Response

```json theme={null}
{
  "errorMessage": "Human-readable error message"
}
```

Or for specific error types:

```json theme={null}
{
  "reason": "modelNotFound"
}
```

## Rate Limiting

API requests are counted per workspace. Every `/v1` response — including `401 Unauthorized` — carries the current limit so a client can throttle before it is rejected.

| Header                                                              | Meaning                                                    |
| ------------------------------------------------------------------- | ---------------------------------------------------------- |
| `RateLimit`                                                         | IETF field: `"workspace";r=<remaining>;t=<window seconds>` |
| `RateLimit-Limit`                                                   | Maximum requests in the current window                     |
| `RateLimit-Remaining`                                               | Requests left in the current window                        |
| `RateLimit-Reset`                                                   | Seconds until the window resets                            |
| `RateLimit-Policy`                                                  | Policy as `<limit>;w=<window seconds>`                     |
| `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` | Legacy spellings of the three quota fields                 |
| `Retry-After`                                                       | On `429` only. Seconds to wait before retrying             |

If you exceed the limit, the API returns `429 Too Many Requests`. Back off by `Retry-After`; do not retry immediately.

## Versioning and deprecation

The API is versioned in the URL path (`/v1`). See [Versioning and deprecation](/api-reference/versioning) for the policy: what counts as breaking, how `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers work, and the 180-day minimum between them.


# List events
Source: https://docs.getcargo.ai/api-reference/mailbox-management--events/list-events

https://api.getcargo.io/openapi.json get /mailboxManagement/events
List sends, opens, clicks, replies, bounces and unsubscribes across the workspace (GET /mailboxManagement/events).



# Create mailbox
Source: https://docs.getcargo.ai/api-reference/mailbox-management--mailboxes/create-mailbox

https://api.getcargo.io/openapi.json post /mailboxManagement/mailboxes
Provision one mailbox on a domain the workspace owns (POST /mailboxManagement/mailboxes).



# Delete mailbox
Source: https://docs.getcargo.ai/api-reference/mailbox-management--mailboxes/delete-mailbox

https://api.getcargo.io/openapi.json delete /mailboxManagement/mailboxes/{uuid}
Delete a mailbox at the provider and stop its warm-up (DELETE /mailboxManagement/mailboxes/{uuid}).



# Get mailbox
Source: https://docs.getcargo.ai/api-reference/mailbox-management--mailboxes/get-mailbox

https://api.getcargo.io/openapi.json get /mailboxManagement/mailboxes/{uuid}
Get a mailbox by UUID (GET /mailboxManagement/mailboxes/{uuid}).



# Get mailbox pricing
Source: https://docs.getcargo.ai/api-reference/mailbox-management--mailboxes/get-mailbox-pricing

https://api.getcargo.io/openapi.json get /mailboxManagement/pricing
Get the monthly credit price of each mailbox type (GET /mailboxManagement/pricing).



# Get mailbox send allowance
Source: https://docs.getcargo.ai/api-reference/mailbox-management--mailboxes/get-mailbox-send-allowance

https://api.getcargo.io/openapi.json get /mailboxManagement/mailboxes/{uuid}/send-allowance
Get how many messages a mailbox may still send today (GET /mailboxManagement/mailboxes/{uuid}/send-allowance).



# Get mailbox warm-up stats
Source: https://docs.getcargo.ai/api-reference/mailbox-management--mailboxes/get-mailbox-warm-up-stats

https://api.getcargo.io/openapi.json get /mailboxManagement/mailboxes/{uuid}/warmup
Get today's warm-up-network sent, inbox and spam counts for a mailbox (GET /mailboxManagement/mailboxes/{uuid}/warmup).



# List mailboxes
Source: https://docs.getcargo.ai/api-reference/mailbox-management--mailboxes/list-mailboxes

https://api.getcargo.io/openapi.json get /mailboxManagement/mailboxes
List the workspace's mailboxes (GET /mailboxManagement/mailboxes).



# Refresh mailbox status
Source: https://docs.getcargo.ai/api-reference/mailbox-management--mailboxes/refresh-mailbox-status

https://api.getcargo.io/openapi.json post /mailboxManagement/mailboxes/{uuid}/refresh-status
Re-poll the provider for a mailbox's status and warm-up (POST /mailboxManagement/mailboxes/{uuid}/refresh-status).



# Start mailbox warm-up
Source: https://docs.getcargo.ai/api-reference/mailbox-management--mailboxes/start-mailbox-warm-up

https://api.getcargo.io/openapi.json post /mailboxManagement/mailboxes/{uuid}/warmup
Start the provider warm-up pool for a mailbox (POST /mailboxManagement/mailboxes/{uuid}/warmup).



# Stop mailbox warm-up
Source: https://docs.getcargo.ai/api-reference/mailbox-management--mailboxes/stop-mailbox-warm-up

https://api.getcargo.io/openapi.json delete /mailboxManagement/mailboxes/{uuid}/warmup
Tear down a mailbox's warm-up pool. Resets the ramp, unlike pausing (DELETE /mailboxManagement/mailboxes/{uuid}/warmup).



# Update mailbox
Source: https://docs.getcargo.ai/api-reference/mailbox-management--mailboxes/update-mailbox

https://api.getcargo.io/openapi.json put /mailboxManagement/mailboxes/{uuid}
Update a mailbox's sender name, signature, or folder. Domain, username and type are create-only (PUT /mailboxManagement/mailboxes/{uuid}).



# Update mailbox warm-up
Source: https://docs.getcargo.ai/api-reference/mailbox-management--mailboxes/update-mailbox-warm-up

https://api.getcargo.io/openapi.json patch /mailboxManagement/mailboxes/{uuid}/warmup
Change a mailbox's warm-up daily target or state (PATCH /mailboxManagement/mailboxes/{uuid}/warmup).



# Get message
Source: https://docs.getcargo.ai/api-reference/mailbox-management--messages/get-message

https://api.getcargo.io/openapi.json get /mailboxManagement/messages/{uuid}
Get a sent message including HTML and text bodies (GET /mailboxManagement/messages/{uuid}).



# List messages
Source: https://docs.getcargo.ai/api-reference/mailbox-management--messages/list-messages

https://api.getcargo.io/openapi.json get /mailboxManagement/messages
List sent-mail log rows (GET /mailboxManagement/messages).



# List suppressions
Source: https://docs.getcargo.ai/api-reference/mailbox-management--suppressions/list-suppressions

https://api.getcargo.io/openapi.json get /mailboxManagement/suppressions
List the addresses the workspace may no longer send to (GET /mailboxManagement/suppressions).



# Suppress an address
Source: https://docs.getcargo.ai/api-reference/mailbox-management--suppressions/suppress-an-address

https://api.getcargo.io/openapi.json post /mailboxManagement/suppressions
Suppress an address by hand, for opt-outs that arrive by reply rather than through the unsubscribe link (POST /mailboxManagement/suppressions).



# Get thread
Source: https://docs.getcargo.ai/api-reference/mailbox-management--threads/get-thread

https://api.getcargo.io/openapi.json get /mailboxManagement/threads/{uuid}
Get a conversation including lastEmail and lastEvent (GET /mailboxManagement/threads/{uuid}).



# List threads
Source: https://docs.getcargo.ai/api-reference/mailbox-management--threads/list-threads

https://api.getcargo.io/openapi.json get /mailboxManagement/threads
List conversations. Each row is a thread with lastEmail and lastEvent attached (GET /mailboxManagement/threads).



# List OAuth grants
Source: https://docs.getcargo.ai/api-reference/oauth--grants/list-oauth-grants

https://api.getcargo.io/openapi.json get /oauth/grants/list
List live OAuth grants for a protected resource (GET /oauth/grants/list).



# Revoke OAuth grant
Source: https://docs.getcargo.ai/api-reference/oauth--grants/revoke-oauth-grant

https://api.getcargo.io/openapi.json delete /oauth/grants/{grantUuid}
Revoke a live OAuth grant for a protected resource (DELETE /oauth/grants/{grantUuid}).



# OpenAPI specification
Source: https://docs.getcargo.ai/api-reference/openapi

The OpenAPI 3.1 document for the Cargo REST API, 280 paths and 340 operations.

The OpenAPI specification is the machine-readable description of the Cargo REST API. Fetch this file rather than scraping HTML.

| URL                                                                                                | What it is                                                  |
| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [https://api.getcargo.io/openapi.json](https://api.getcargo.io/openapi.json)                       | Canonical OpenAPI 3.1.0 document, 280 paths, 340 operations |
| [https://www.getcargo.ai/openapi.json](https://www.getcargo.ai/openapi.json)                       | Same document, served on the product domain                 |
| [https://www.getcargo.ai/.well-known/api-catalog](https://www.getcargo.ai/.well-known/api-catalog) | RFC 9727 catalog pointing at the spec                       |

`/openapi` and `/spec` on getcargo.ai rewrite to `/openapi.json`.

The spec describes:

* The REST server at `https://api.getcargo.io/v1`
* Bearer and OAuth 2.0 security schemes, including named scopes
* Typed request and response schemas
* `Idempotency-Key` on write operations
* A shared error schema on 4xx and 5xx responses
* `Deprecation` and `Sunset` headers on retired operations

See [API Reference](/api-reference/introduction) for the prose companion and [Authentication](/api-reference/authentication) for how to get a token.


# Execute action
Source: https://docs.getcargo.ai/api-reference/orchestration--actions/execute-action

https://api.getcargo.io/openapi.json post /orchestration/actions/execute
Execute an orchestration action. Without waitUntilFinished the response is 202 Accepted: poll Location until the run reaches a terminal status. Set waitUntilFinished to block until the run completes (up to 5 minutes); a finished run is 200. (POST /orchestration/actions/execute).



# Execute action batch
Source: https://docs.getcargo.ai/api-reference/orchestration--actions/execute-action-batch

https://api.getcargo.io/openapi.json post /orchestration/actions/execute-batch
Execute an orchestration action as a batch. Without waitUntilFinished the response is 202 Accepted: poll Location until the batch reaches a terminal status. Set waitUntilFinished to block until the batch completes (up to 5 minutes); a finished batch is 200. (POST /orchestration/actions/execute-batch).



# Get action output schema
Source: https://docs.getcargo.ai/api-reference/orchestration--actions/get-action-output-schema

https://api.getcargo.io/openapi.json post /orchestration/actions/get-output-schema
Get the output schema of an orchestration action (POST /orchestration/actions/get-output-schema).



# List actions
Source: https://docs.getcargo.ai/api-reference/orchestration--actions/list-actions

https://api.getcargo.io/openapi.json get /orchestration/actions/list
List connector, native, tool, and agent actions. Unauthenticated requests return the public connector and native catalog; tools, agents, custom integrations, and workspace connectors require a signed-in workspace. Each result includes an action payload for execute, execute-batch, or get-output-schema. (GET /orchestration/actions/list).



# Cancel batch
Source: https://docs.getcargo.ai/api-reference/orchestration--batches/cancel-batch

https://api.getcargo.io/openapi.json post /orchestration/batches/{uuid}/cancel
Cancel a running batch (POST /orchestration/batches/{uuid}/cancel).



# Create batch
Source: https://docs.getcargo.ai/api-reference/orchestration--batches/create-batch

https://api.getcargo.io/openapi.json post /orchestration/batches
Create a new orchestration batch. Returns 202 Accepted; poll Location until the batch reaches a terminal status. (POST /orchestration/batches).



# Download batch
Source: https://docs.getcargo.ai/api-reference/orchestration--batches/download-batch

https://api.getcargo.io/openapi.json post /orchestration/batches/{uuid}/download
Download batch results (POST /orchestration/batches/{uuid}/download).



# Get batch
Source: https://docs.getcargo.ai/api-reference/orchestration--batches/get-batch

https://api.getcargo.io/openapi.json get /orchestration/batches/{uuid}
Get an orchestration batch by UUID. This is the status resource returned as Location from POST /orchestration/batches. (GET /orchestration/batches/{uuid}).



# List batches
Source: https://docs.getcargo.ai/api-reference/orchestration--batches/list-batches

https://api.getcargo.io/openapi.json get /orchestration/batches/list
List all orchestration batches (GET /orchestration/batches/list).



# Preview batch
Source: https://docs.getcargo.ai/api-reference/orchestration--batches/preview-batch

https://api.getcargo.io/openapi.json post /orchestration/batches/preview
Preview batch data before execution (POST /orchestration/batches/preview).



# Compute node
Source: https://docs.getcargo.ai/api-reference/orchestration--nodes/compute-node

https://api.getcargo.io/openapi.json post /orchestration/nodes/compute
Compute node output (POST /orchestration/nodes/compute).



# Execute node
Source: https://docs.getcargo.ai/api-reference/orchestration--nodes/execute-node

https://api.getcargo.io/openapi.json post /orchestration/nodes/execute
Execute a node (POST /orchestration/nodes/execute).



# Validate nodes
Source: https://docs.getcargo.ai/api-reference/orchestration--nodes/validate-nodes

https://api.getcargo.io/openapi.json post /orchestration/nodes/validate
Validate orchestration nodes (POST /orchestration/nodes/validate).



# Create play
Source: https://docs.getcargo.ai/api-reference/orchestration--plays/create-play

https://api.getcargo.io/openapi.json post /orchestration/plays
Create a new play (POST /orchestration/plays).



# Get play
Source: https://docs.getcargo.ai/api-reference/orchestration--plays/get-play

https://api.getcargo.io/openapi.json get /orchestration/plays/{uuid}
Get a play by UUID (GET /orchestration/plays/{uuid}).



# List plays
Source: https://docs.getcargo.ai/api-reference/orchestration--plays/list-plays

https://api.getcargo.io/openapi.json get /orchestration/plays/list
List all plays (GET /orchestration/plays/list).



# Remove play
Source: https://docs.getcargo.ai/api-reference/orchestration--plays/remove-play

https://api.getcargo.io/openapi.json delete /orchestration/plays/{uuid}
Remove a play (DELETE /orchestration/plays/{uuid}).



# Update play
Source: https://docs.getcargo.ai/api-reference/orchestration--plays/update-play

https://api.getcargo.io/openapi.json put /orchestration/plays/{uuid}
Update a play (PUT /orchestration/plays/{uuid}).



# Execute SQL query
Source: https://docs.getcargo.ai/api-reference/orchestration--query/execute-sql-query

https://api.getcargo.io/openapi.json post /orchestration/query
Execute a read-only SQL query against orchestration ClickHouse tables (spans, runs, batches, records).  (POST /orchestration/query).



# Cancel records
Source: https://docs.getcargo.ai/api-reference/orchestration--records/cancel-records

https://api.getcargo.io/openapi.json post /orchestration/records/cancel
Cancel running orchestration records (POST /orchestration/records/cancel).



# Count records
Source: https://docs.getcargo.ai/api-reference/orchestration--records/count-records

https://api.getcargo.io/openapi.json post /orchestration/records/count
Count orchestration records (POST /orchestration/records/count).



# Download record outputs
Source: https://docs.getcargo.ai/api-reference/orchestration--records/download-record-outputs

https://api.getcargo.io/openapi.json post /orchestration/records/download-outputs
Download orchestration record outputs with input and output node contexts (POST /orchestration/records/download-outputs).



# Download records
Source: https://docs.getcargo.ai/api-reference/orchestration--records/download-records

https://api.getcargo.io/openapi.json post /orchestration/records/download
Download orchestration records (POST /orchestration/records/download).



# Get record metrics
Source: https://docs.getcargo.ai/api-reference/orchestration--records/get-record-metrics

https://api.getcargo.io/openapi.json post /orchestration/records/metrics
Get metrics for orchestration records (POST /orchestration/records/metrics).



# List records
Source: https://docs.getcargo.ai/api-reference/orchestration--records/list-records

https://api.getcargo.io/openapi.json post /orchestration/records/list
List orchestration records (POST /orchestration/records/list).



# Deploy draft release
Source: https://docs.getcargo.ai/api-reference/orchestration--releases/deploy-draft-release

https://api.getcargo.io/openapi.json post /orchestration/releases/draft/deploy
Deploy a draft release (POST /orchestration/releases/draft/deploy).



# Get deployed release
Source: https://docs.getcargo.ai/api-reference/orchestration--releases/get-deployed-release

https://api.getcargo.io/openapi.json get /orchestration/releases/deployed
Get the deployed release (GET /orchestration/releases/deployed).



# Get draft release
Source: https://docs.getcargo.ai/api-reference/orchestration--releases/get-draft-release

https://api.getcargo.io/openapi.json get /orchestration/releases/draft
Get the draft release (GET /orchestration/releases/draft).



# Get release
Source: https://docs.getcargo.ai/api-reference/orchestration--releases/get-release

https://api.getcargo.io/openapi.json get /orchestration/releases/{uuid}
Get a release by UUID (GET /orchestration/releases/{uuid}).



# List releases
Source: https://docs.getcargo.ai/api-reference/orchestration--releases/list-releases

https://api.getcargo.io/openapi.json get /orchestration/releases/list
List all releases (GET /orchestration/releases/list).



# Update draft release
Source: https://docs.getcargo.ai/api-reference/orchestration--releases/update-draft-release

https://api.getcargo.io/openapi.json post /orchestration/releases/draft/update
Update the draft release (POST /orchestration/releases/draft/update).



# Cancel runs
Source: https://docs.getcargo.ai/api-reference/orchestration--runs/cancel-runs

https://api.getcargo.io/openapi.json post /orchestration/runs/cancel
Cancel running orchestration runs (POST /orchestration/runs/cancel).



# Count runs
Source: https://docs.getcargo.ai/api-reference/orchestration--runs/count-runs

https://api.getcargo.io/openapi.json post /orchestration/runs/count
Count orchestration runs (POST /orchestration/runs/count).



# Create run
Source: https://docs.getcargo.ai/api-reference/orchestration--runs/create-run

https://api.getcargo.io/openapi.json post /orchestration/runs
Create a new orchestration run. Returns 202 Accepted; poll Location until the run reaches a terminal status. (POST /orchestration/runs).



# Download run outputs
Source: https://docs.getcargo.ai/api-reference/orchestration--runs/download-run-outputs

https://api.getcargo.io/openapi.json post /orchestration/runs/download-outputs
Download orchestration run outputs with input and output node contexts (POST /orchestration/runs/download-outputs).



# Download runs
Source: https://docs.getcargo.ai/api-reference/orchestration--runs/download-runs

https://api.getcargo.io/openapi.json post /orchestration/runs/download
Download orchestration runs (POST /orchestration/runs/download).



# Get run
Source: https://docs.getcargo.ai/api-reference/orchestration--runs/get-run

https://api.getcargo.io/openapi.json get /orchestration/runs/{uuid}
Get an orchestration run by UUID. This is the status resource returned as Location from POST /orchestration/runs. (GET /orchestration/runs/{uuid}).



# Get run metrics
Source: https://docs.getcargo.ai/api-reference/orchestration--runs/get-run-metrics

https://api.getcargo.io/openapi.json post /orchestration/runs/metrics
Get metrics for orchestration runs (POST /orchestration/runs/metrics).



# List runs
Source: https://docs.getcargo.ai/api-reference/orchestration--runs/list-runs

https://api.getcargo.io/openapi.json post /orchestration/runs/list
List orchestration runs (POST /orchestration/runs/list).



# Count spans
Source: https://docs.getcargo.ai/api-reference/orchestration--spans/count-spans

https://api.getcargo.io/openapi.json post /orchestration/spans/count
Count orchestration execution spans (POST /orchestration/spans/count).



# List spans
Source: https://docs.getcargo.ai/api-reference/orchestration--spans/list-spans

https://api.getcargo.io/openapi.json post /orchestration/spans/list
List flattened execution spans for orchestration runs (one row per executed node within a run) (POST /orchestration/spans/list).



# Get template
Source: https://docs.getcargo.ai/api-reference/orchestration--templates/get-template

https://api.getcargo.io/openapi.json get /orchestration/templates/{slug}
Get an orchestration template by slug (GET /orchestration/templates/{slug}).



# Get template documentation
Source: https://docs.getcargo.ai/api-reference/orchestration--templates/get-template-documentation

https://api.getcargo.io/openapi.json get /orchestration/templates/{slug}/documentation
Get the documentation for an orchestration template (GET /orchestration/templates/{slug}/documentation).



# List templates
Source: https://docs.getcargo.ai/api-reference/orchestration--templates/list-templates

https://api.getcargo.io/openapi.json post /orchestration/templates/list
List all orchestration templates (POST /orchestration/templates/list).



# Create tool
Source: https://docs.getcargo.ai/api-reference/orchestration--tools/create-tool

https://api.getcargo.io/openapi.json post /orchestration/tools
Create a new tool (POST /orchestration/tools).



# Get tool
Source: https://docs.getcargo.ai/api-reference/orchestration--tools/get-tool

https://api.getcargo.io/openapi.json get /orchestration/tools/{uuid}
Get a tool by UUID (GET /orchestration/tools/{uuid}).



# List tools
Source: https://docs.getcargo.ai/api-reference/orchestration--tools/list-tools

https://api.getcargo.io/openapi.json get /orchestration/tools/list
List all tools (GET /orchestration/tools/list).



# Remove tool
Source: https://docs.getcargo.ai/api-reference/orchestration--tools/remove-tool

https://api.getcargo.io/openapi.json delete /orchestration/tools/{uuid}
Remove a tool (DELETE /orchestration/tools/{uuid}).



# Update tool
Source: https://docs.getcargo.ai/api-reference/orchestration--tools/update-tool

https://api.getcargo.io/openapi.json put /orchestration/tools/{uuid}
Update a tool (PUT /orchestration/tools/{uuid}).



# Count traces
Source: https://docs.getcargo.ai/api-reference/orchestration--traces/count-traces

https://api.getcargo.io/openapi.json post /orchestration/traces/count
Count orchestration traces matching the filter. (POST /orchestration/traces/count).



# Get trace
Source: https://docs.getcargo.ai/api-reference/orchestration--traces/get-trace

https://api.getcargo.io/openapi.json get /orchestration/traces/{uuid}
Get a single orchestration trace by UUID. (GET /orchestration/traces/{uuid}).



# List traces
Source: https://docs.getcargo.ai/api-reference/orchestration--traces/list-traces

https://api.getcargo.io/openapi.json post /orchestration/traces/list
List orchestration traces. Each trace wraps every span (node execution) across its run lineage; the summary is aggregated at query time directly from orchestration.spans (no separate traces table — spans carries `trace_uuid` with a bloom-filter skipping index). (POST /orchestration/traces/list).



# Get workflow
Source: https://docs.getcargo.ai/api-reference/orchestration--workflows/get-workflow

https://api.getcargo.io/openapi.json get /orchestration/workflows/{uuid}
Get a workflow by UUID (GET /orchestration/workflows/{uuid}).



# List workflows
Source: https://docs.getcargo.ai/api-reference/orchestration--workflows/list-workflows

https://api.getcargo.io/openapi.json get /orchestration/workflows/list
List all workflows (GET /orchestration/workflows/list).



# Get allocation
Source: https://docs.getcargo.ai/api-reference/revenue-organization--allocations/get-allocation

https://api.getcargo.io/openapi.json get /revenueOrganization/allocations/{uuid}
Get an allocation by UUID (GET /revenueOrganization/allocations/{uuid}).



# List allocations
Source: https://docs.getcargo.ai/api-reference/revenue-organization--allocations/list-allocations

https://api.getcargo.io/openapi.json get /revenueOrganization/allocations/list
List all allocations (GET /revenueOrganization/allocations/list).



# Remove allocation
Source: https://docs.getcargo.ai/api-reference/revenue-organization--allocations/remove-allocation

https://api.getcargo.io/openapi.json delete /revenueOrganization/allocations/{uuid}
Remove an allocation (DELETE /revenueOrganization/allocations/{uuid}).



# Sync allocations
Source: https://docs.getcargo.ai/api-reference/revenue-organization--allocations/sync-allocations

https://api.getcargo.io/openapi.json post /revenueOrganization/allocations/sync
Sync allocations from external source (POST /revenueOrganization/allocations/sync).



# Create capacity
Source: https://docs.getcargo.ai/api-reference/revenue-organization--capacities/create-capacity

https://api.getcargo.io/openapi.json post /revenueOrganization/capacities
Create a new capacity (POST /revenueOrganization/capacities).



# Get capacity
Source: https://docs.getcargo.ai/api-reference/revenue-organization--capacities/get-capacity

https://api.getcargo.io/openapi.json get /revenueOrganization/capacities/{uuid}
Get a capacity by UUID (GET /revenueOrganization/capacities/{uuid}).



# List capacities
Source: https://docs.getcargo.ai/api-reference/revenue-organization--capacities/list-capacities

https://api.getcargo.io/openapi.json get /revenueOrganization/capacities/list
List all capacities (GET /revenueOrganization/capacities/list).



# Remove capacity
Source: https://docs.getcargo.ai/api-reference/revenue-organization--capacities/remove-capacity

https://api.getcargo.io/openapi.json delete /revenueOrganization/capacities/{uuid}
Remove a capacity (DELETE /revenueOrganization/capacities/{uuid}).



# Update capacity
Source: https://docs.getcargo.ai/api-reference/revenue-organization--capacities/update-capacity

https://api.getcargo.io/openapi.json put /revenueOrganization/capacities/{uuid}
Update a capacity (PUT /revenueOrganization/capacities/{uuid}).



# Archive member
Source: https://docs.getcargo.ai/api-reference/revenue-organization--members/archive-member

https://api.getcargo.io/openapi.json post /revenueOrganization/members/{uuid}/archive
Archive a member (POST /revenueOrganization/members/{uuid}/archive).



# Get member
Source: https://docs.getcargo.ai/api-reference/revenue-organization--members/get-member

https://api.getcargo.io/openapi.json get /revenueOrganization/members/{uuid}
Get a member by UUID (GET /revenueOrganization/members/{uuid}).



# List members
Source: https://docs.getcargo.ai/api-reference/revenue-organization--members/list-members

https://api.getcargo.io/openapi.json get /revenueOrganization/members/list
List all members (GET /revenueOrganization/members/list).



# Sync members
Source: https://docs.getcargo.ai/api-reference/revenue-organization--members/sync-members

https://api.getcargo.io/openapi.json post /revenueOrganization/members/sync
Sync members from external source (POST /revenueOrganization/members/sync).



# Unarchive member
Source: https://docs.getcargo.ai/api-reference/revenue-organization--members/unarchive-member

https://api.getcargo.io/openapi.json post /revenueOrganization/members/{uuid}/unarchive
Unarchive a member (POST /revenueOrganization/members/{uuid}/unarchive).



# Update member
Source: https://docs.getcargo.ai/api-reference/revenue-organization--members/update-member

https://api.getcargo.io/openapi.json put /revenueOrganization/members/{uuid}
Update a member (PUT /revenueOrganization/members/{uuid}).



# Create territory
Source: https://docs.getcargo.ai/api-reference/revenue-organization--territories/create-territory

https://api.getcargo.io/openapi.json post /revenueOrganization/territories
Create a new territory (POST /revenueOrganization/territories).



# Get territory
Source: https://docs.getcargo.ai/api-reference/revenue-organization--territories/get-territory

https://api.getcargo.io/openapi.json get /revenueOrganization/territories/{uuid}
Get a territory by UUID (GET /revenueOrganization/territories/{uuid}).



# List territories
Source: https://docs.getcargo.ai/api-reference/revenue-organization--territories/list-territories

https://api.getcargo.io/openapi.json get /revenueOrganization/territories/list
List all territories (GET /revenueOrganization/territories/list).



# Remove territory
Source: https://docs.getcargo.ai/api-reference/revenue-organization--territories/remove-territory

https://api.getcargo.io/openapi.json delete /revenueOrganization/territories/{uuid}
Remove a territory (DELETE /revenueOrganization/territories/{uuid}).



# Update territory
Source: https://docs.getcargo.ai/api-reference/revenue-organization--territories/update-territory

https://api.getcargo.io/openapi.json put /revenueOrganization/territories/{uuid}
Update a territory (PUT /revenueOrganization/territories/{uuid}).



# Download change data
Source: https://docs.getcargo.ai/api-reference/segmentation--changes/download-change-data

https://api.getcargo.io/openapi.json post /segmentation/changes/{uuid}/download
Download data for a segment change (POST /segmentation/changes/{uuid}/download).



# Fetch change data
Source: https://docs.getcargo.ai/api-reference/segmentation--changes/fetch-change-data

https://api.getcargo.io/openapi.json post /segmentation/changes/{uuid}/fetch
Fetch data for a segment change (POST /segmentation/changes/{uuid}/fetch).



# Get change
Source: https://docs.getcargo.ai/api-reference/segmentation--changes/get-change

https://api.getcargo.io/openapi.json get /segmentation/changes/{uuid}
Get a segment change by UUID (GET /segmentation/changes/{uuid}).



# List changes
Source: https://docs.getcargo.ai/api-reference/segmentation--changes/list-changes

https://api.getcargo.io/openapi.json get /segmentation/changes/list
List all segment changes (GET /segmentation/changes/list).



# Fetch records
Source: https://docs.getcargo.ai/api-reference/segmentation--records/fetch-records

https://api.getcargo.io/openapi.json post /segmentation/records/fetch
Fetch segmentation records (POST /segmentation/records/fetch).



# Create segment
Source: https://docs.getcargo.ai/api-reference/segmentation--segments/create-segment

https://api.getcargo.io/openapi.json post /segmentation/segments
Create a new segment (POST /segmentation/segments).



# Download segment data
Source: https://docs.getcargo.ai/api-reference/segmentation--segments/download-segment-data

https://api.getcargo.io/openapi.json post /segmentation/segments/download
Download data for a segment (POST /segmentation/segments/download).



# Fetch segment data
Source: https://docs.getcargo.ai/api-reference/segmentation--segments/fetch-segment-data

https://api.getcargo.io/openapi.json post /segmentation/segments/fetch
Fetch data for a segment (POST /segmentation/segments/fetch).



# Get segment
Source: https://docs.getcargo.ai/api-reference/segmentation--segments/get-segment

https://api.getcargo.io/openapi.json get /segmentation/segments/{uuid}
Get a segment by UUID (GET /segmentation/segments/{uuid}).



# Get segment metrics
Source: https://docs.getcargo.ai/api-reference/segmentation--segments/get-segment-metrics

https://api.getcargo.io/openapi.json get /segmentation/segments/{uuid}/metrics
Get metrics for a segment (GET /segmentation/segments/{uuid}/metrics).



# List segments
Source: https://docs.getcargo.ai/api-reference/segmentation--segments/list-segments

https://api.getcargo.io/openapi.json get /segmentation/segments/list
List all segments (GET /segmentation/segments/list).



# Remove segment
Source: https://docs.getcargo.ai/api-reference/segmentation--segments/remove-segment

https://api.getcargo.io/openapi.json delete /segmentation/segments/{uuid}
Remove a segment (DELETE /segmentation/segments/{uuid}).



# Update segment
Source: https://docs.getcargo.ai/api-reference/segmentation--segments/update-segment

https://api.getcargo.io/openapi.json put /segmentation/segments/{uuid}
Update a segment (PUT /segmentation/segments/{uuid}).



# Autocomplete columns
Source: https://docs.getcargo.ai/api-reference/storage--columns/autocomplete-columns

https://api.getcargo.io/openapi.json post /storage/columns/autocomplete
Get column autocomplete suggestions (POST /storage/columns/autocomplete).



# Check column exists by slug
Source: https://docs.getcargo.ai/api-reference/storage--columns/check-column-exists-by-slug

https://api.getcargo.io/openapi.json get /storage/columns/existsBySlug
Check if a column exists by its slug (GET /storage/columns/existsBySlug).



# Create column
Source: https://docs.getcargo.ai/api-reference/storage--columns/create-column

https://api.getcargo.io/openapi.json post /storage/columns
Create a new column for a model (POST /storage/columns).



# Insert custom column values
Source: https://docs.getcargo.ai/api-reference/storage--columns/insert-custom-column-values

https://api.getcargo.io/openapi.json post /storage/columns/insertCustomValues
Set custom column values on a single record. Original object fields are not accepted; use record create/update for those. (POST /storage/columns/insertCustomValues).



# Insert custom column values (bulk)
Source: https://docs.getcargo.ai/api-reference/storage--columns/insert-custom-column-values-bulk

https://api.getcargo.io/openapi.json post /storage/columns/insertCustomValuesBulk
Set custom column values on multiple records. Original object fields are not accepted; use record create/update for those. (POST /storage/columns/insertCustomValuesBulk).



# List model columns
Source: https://docs.getcargo.ai/api-reference/storage--columns/list-model-columns

https://api.getcargo.io/openapi.json get /storage/columns/list
List all columns for a model, using prefixed slugs for additional columns (GET /storage/columns/list).



# Remove column
Source: https://docs.getcargo.ai/api-reference/storage--columns/remove-column

https://api.getcargo.io/openapi.json delete /storage/columns
Remove a column by UUID (DELETE /storage/columns).



# Reorder columns
Source: https://docs.getcargo.ai/api-reference/storage--columns/reorder-columns

https://api.getcargo.io/openapi.json put /storage/columns/reorder
Reorder columns for a model (PUT /storage/columns/reorder).



# Update column
Source: https://docs.getcargo.ai/api-reference/storage--columns/update-column

https://api.getcargo.io/openapi.json put /storage/columns
Update a column by UUID (PUT /storage/columns).



# Get dataset
Source: https://docs.getcargo.ai/api-reference/storage--datasets/get-dataset

https://api.getcargo.io/openapi.json get /storage/datasets/{uuid}
Get a dataset by UUID (GET /storage/datasets/{uuid}).



# List datasets
Source: https://docs.getcargo.ai/api-reference/storage--datasets/list-datasets

https://api.getcargo.io/openapi.json get /storage/datasets/list
List all datasets in the workspace (GET /storage/datasets/list).



# Check model exists by slug
Source: https://docs.getcargo.ai/api-reference/storage--models/check-model-exists-by-slug

https://api.getcargo.io/openapi.json get /storage/models/existsBySlug
Check if a model exists by its slug (GET /storage/models/existsBySlug).



# Create model
Source: https://docs.getcargo.ai/api-reference/storage--models/create-model

https://api.getcargo.io/openapi.json post /storage/models
Create a new model (POST /storage/models).



# Get model
Source: https://docs.getcargo.ai/api-reference/storage--models/get-model

https://api.getcargo.io/openapi.json get /storage/models/{uuid}
Get a model by UUID (GET /storage/models/{uuid}).



# Get model DDL
Source: https://docs.getcargo.ai/api-reference/storage--models/get-model-ddl

https://api.getcargo.io/openapi.json get /storage/models/{uuid}/ddl
Get the DDL for a model's table in the system of record (GET /storage/models/{uuid}/ddl).



# List models
Source: https://docs.getcargo.ai/api-reference/storage--models/list-models

https://api.getcargo.io/openapi.json get /storage/models/list
List all models in the workspace (GET /storage/models/list).



# Preview model
Source: https://docs.getcargo.ai/api-reference/storage--models/preview-model

https://api.getcargo.io/openapi.json post /storage/models/preview
Preview model data (POST /storage/models/preview).



# Preview model count
Source: https://docs.getcargo.ai/api-reference/storage--models/preview-model-count

https://api.getcargo.io/openapi.json post /storage/models/previewCount
Get preview count for model data (POST /storage/models/previewCount).



# Refresh model
Source: https://docs.getcargo.ai/api-reference/storage--models/refresh-model

https://api.getcargo.io/openapi.json post /storage/models/{uuid}/refresh
Refresh a model's tables with the latest data (POST /storage/models/{uuid}/refresh).



# Remove model
Source: https://docs.getcargo.ai/api-reference/storage--models/remove-model

https://api.getcargo.io/openapi.json delete /storage/models/{uuid}
Remove a model by UUID (DELETE /storage/models/{uuid}).



# Update model
Source: https://docs.getcargo.ai/api-reference/storage--models/update-model

https://api.getcargo.io/openapi.json put /storage/models/{uuid}
Update a model by UUID (PUT /storage/models/{uuid}).



# Download SQL query results
Source: https://docs.getcargo.ai/api-reference/storage--query/download-sql-query-results

https://api.getcargo.io/openapi.json post /storage/query/download
Execute a read-only SELECT query against the workspace's storage warehouse and download the results as a file. (POST /storage/query/download).



# Execute SQL query
Source: https://docs.getcargo.ai/api-reference/storage--query/execute-sql-query

https://api.getcargo.io/openapi.json post /storage/query
Execute a read-only SELECT query against the workspace's storage warehouse. Tables must be referenced as [datasetSlug].[modelSlug] and are rewritten to the underlying warehouse table under the hood. (POST /storage/query).



# Create record
Source: https://docs.getcargo.ai/api-reference/storage--records/create-record

https://api.getcargo.io/openapi.json post /storage/records/create
Insert a single model row. Body: { modelUuid, data } where data is the row fields. (POST /storage/records/create).



# Create records (bulk)
Source: https://docs.getcargo.ai/api-reference/storage--records/create-records-bulk

https://api.getcargo.io/openapi.json post /storage/records/createBulk
Insert multiple model rows in one call. Body: { modelUuid, records: [{ data }, ...] }. (POST /storage/records/createBulk).



# Get record
Source: https://docs.getcargo.ai/api-reference/storage--records/get-record

https://api.getcargo.io/openapi.json get /storage/records/get
Get a record for a model by ID (GET /storage/records/get).



# List records
Source: https://docs.getcargo.ai/api-reference/storage--records/list-records

https://api.getcargo.io/openapi.json post /storage/records/list
List records for a model (POST /storage/records/list).



# Remove record
Source: https://docs.getcargo.ai/api-reference/storage--records/remove-record

https://api.getcargo.io/openapi.json delete /storage/records/remove
Remove a single row. Body: { modelUuid, id }. (DELETE /storage/records/remove).



# Remove records (bulk)
Source: https://docs.getcargo.ai/api-reference/storage--records/remove-records-bulk

https://api.getcargo.io/openapi.json delete /storage/records/removeBulk
Remove multiple rows in one call. Body: { modelUuid, ids: [string, ...] }. (DELETE /storage/records/removeBulk).



# Update record
Source: https://docs.getcargo.ai/api-reference/storage--records/update-record

https://api.getcargo.io/openapi.json put /storage/records/update
Update a single row. Body: { modelUuid, id, data }; data is merged then id is set under the model id column slug. (PUT /storage/records/update).



# Update records (bulk)
Source: https://docs.getcargo.ai/api-reference/storage--records/update-records-bulk

https://api.getcargo.io/openapi.json put /storage/records/updateBulk
Update multiple rows in one call. Body: { modelUuid, records: [{ id, data }, ...] }. (PUT /storage/records/updateBulk).



# Get relationship
Source: https://docs.getcargo.ai/api-reference/storage--relationships/get-relationship

https://api.getcargo.io/openapi.json get /storage/relationships/{uuid}
Get a relationship by UUID (GET /storage/relationships/{uuid}).



# List relationships
Source: https://docs.getcargo.ai/api-reference/storage--relationships/list-relationships

https://api.getcargo.io/openapi.json get /storage/relationships/list
List all relationships in the workspace (GET /storage/relationships/list).



# Set relationship
Source: https://docs.getcargo.ai/api-reference/storage--relationships/set-relationship

https://api.getcargo.io/openapi.json post /storage/relationships
Set relationships between models within a connector dataset, or between native object models within the native dataset. Native unify models are not supported. (POST /storage/relationships).



# Cancel run
Source: https://docs.getcargo.ai/api-reference/storage--runs/cancel-run

https://api.getcargo.io/openapi.json post /storage/runs/{uuid}/cancel
Cancel a running model sync (POST /storage/runs/{uuid}/cancel).



# Create run
Source: https://docs.getcargo.ai/api-reference/storage--runs/create-run

https://api.getcargo.io/openapi.json post /storage/runs
Create a new model sync run (POST /storage/runs).



# List runs
Source: https://docs.getcargo.ai/api-reference/storage--runs/list-runs

https://api.getcargo.io/openapi.json get /storage/runs/list
List model sync runs (GET /storage/runs/list).



# Download client data
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--clients/download-client-data

https://api.getcargo.io/openapi.json post /systemOfRecordIntegration/clients/download
Download data from a system of record client (POST /systemOfRecordIntegration/clients/download).



# Fetch client data
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--clients/fetch-client-data

https://api.getcargo.io/openapi.json post /systemOfRecordIntegration/clients/fetch
Fetch data from a system of record client (POST /systemOfRecordIntegration/clients/fetch).



# Get client documentation
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--clients/get-client-documentation

https://api.getcargo.io/openapi.json get /systemOfRecordIntegration/clients/{slug}/documentation
Get documentation for a system of record client (GET /systemOfRecordIntegration/clients/{slug}/documentation).



# List clients
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--clients/list-clients

https://api.getcargo.io/openapi.json get /systemOfRecordIntegration/clients/list
List all system of record clients (GET /systemOfRecordIntegration/clients/list).



# Query client
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--clients/query-client

https://api.getcargo.io/openapi.json post /systemOfRecordIntegration/clients/query
Query data from a system of record client (POST /systemOfRecordIntegration/clients/query).



# Get log metrics
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--logs/get-log-metrics

https://api.getcargo.io/openapi.json get /systemOfRecordIntegration/logs/metrics
Get metrics for system of record integration logs (GET /systemOfRecordIntegration/logs/metrics).



# List logs
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--logs/list-logs

https://api.getcargo.io/openapi.json get /systemOfRecordIntegration/logs/list
List system of record integration logs (GET /systemOfRecordIntegration/logs/list).



# Create system of record
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--systems-of-record/create-system-of-record

https://api.getcargo.io/openapi.json post /systemOfRecordIntegration/systemOfRecords
Create a new system of record (POST /systemOfRecordIntegration/systemOfRecords).



# Cutover system of record
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--systems-of-record/cutover-system-of-record

https://api.getcargo.io/openapi.json post /systemOfRecordIntegration/systemOfRecords/{uuid}/cutover
Perform cutover for a system of record (POST /systemOfRecordIntegration/systemOfRecords/{uuid}/cutover).



# Get system of record
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--systems-of-record/get-system-of-record

https://api.getcargo.io/openapi.json get /systemOfRecordIntegration/systemOfRecords/{uuid}
Get a system of record by UUID (GET /systemOfRecordIntegration/systemOfRecords/{uuid}).



# List systems of record
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--systems-of-record/list-systems-of-record

https://api.getcargo.io/openapi.json get /systemOfRecordIntegration/systemOfRecords
List all systems of record (GET /systemOfRecordIntegration/systemOfRecords).



# Migrate system of record
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--systems-of-record/migrate-system-of-record

https://api.getcargo.io/openapi.json post /systemOfRecordIntegration/systemOfRecords/{uuid}/migrate
Migrate data to a system of record (POST /systemOfRecordIntegration/systemOfRecords/{uuid}/migrate).



# Remove system of record
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--systems-of-record/remove-system-of-record

https://api.getcargo.io/openapi.json delete /systemOfRecordIntegration/systemOfRecords/{uuid}
Remove a system of record (DELETE /systemOfRecordIntegration/systemOfRecords/{uuid}).



# Update system of record
Source: https://docs.getcargo.ai/api-reference/system-of-record-integration--systems-of-record/update-system-of-record

https://api.getcargo.io/openapi.json put /systemOfRecordIntegration/systemOfRecords/{uuid}
Update a system of record (PUT /systemOfRecordIntegration/systemOfRecords/{uuid}).



# Get current user
Source: https://docs.getcargo.ai/api-reference/user-management--users/get-current-user

https://api.getcargo.io/openapi.json get /userManagement/users/current
Get the current authenticated user (GET /userManagement/users/current).



# Update current user
Source: https://docs.getcargo.ai/api-reference/user-management--users/update-current-user

https://api.getcargo.io/openapi.json put /userManagement/users/current
Update the current authenticated user (PUT /userManagement/users/current).



# Versioning and deprecation
Source: https://docs.getcargo.ai/api-reference/versioning

How the Cargo REST API is versioned, what counts as breaking, and how Deprecation (RFC 9745) and Sunset (RFC 8594) headers signal retirement.

The Cargo REST API is versioned in the URL path. Breaking changes ship as a
new path; they never mutate an existing version. When an operation is
retired it is signalled with the `Deprecation` (RFC 9745) and `Sunset`
(RFC 8594) headers, and it keeps answering until the sunset date.

This is the deprecation policy. Agents can rely on it.

## Versioning

The current version is **v1**, addressed at:

```
https://api.getcargo.io/v1
```

The version is in the path, not in a header. A breaking change is published
as `/v2` (or later) rather than by changing `/v1`. Clients pin the path they
were built against.

The OpenAPI description of this version is at
[https://api.getcargo.io/openapi.json](https://api.getcargo.io/openapi.json)
and at [https://www.getcargo.ai/openapi.json](https://www.getcargo.ai/openapi.json).

## What is not a breaking change

These are additive and can appear on `/v1` without a new version:

* A new endpoint.
* A new optional request field. Existing clients that do not send it keep
  working.
* A new field on a response. Clients must ignore fields they do not
  recognise; treating the JSON as a closed object is the thing that breaks.
* A new optional header.

A change is breaking when a request that worked keeps the same path and
stops working, or when a field a client already reads changes type or
meaning.

## Deprecation policy

When an operation on a published version is going to be removed:

1. The operation is marked `deprecated` in the OpenAPI document.
2. Every response from that operation carries the `Deprecation` header
   (RFC 9745). The value is an HTTP-date: the moment deprecation began.
3. Once a removal date is fixed, the same responses also carry the `Sunset`
   header (RFC 8594). The value is an HTTP-date: the moment the operation
   will stop being served.
4. There are at least **180 days** between the `Deprecation` date and the
   `Sunset` date. The operation keeps answering, with both headers, until
   sunset.
5. After sunset the path returns `410 Gone`. A new version of the same
   capability, if any, lives on a new path.

No currently published `/v1` operation is deprecated. The headers above
appear only when one is.

A `Link` header with `rel="deprecation"` or `rel="sunset"` may point at
this page for the human-readable explanation of a specific retirement.

## Headers

| Header        | RFC  | When it appears                         | Value                                      |
| ------------- | ---- | --------------------------------------- | ------------------------------------------ |
| `Deprecation` | 9745 | The operation is deprecated             | HTTP-date of when deprecation began        |
| `Sunset`      | 8594 | A removal date has been set             | HTTP-date of when the operation is removed |
| `Link`        | 8288 | Alongside either of the above, optional | URL of this policy, `rel="deprecation"`    |

Example of a response for an operation that was deprecated on 1 August 2026
and will be removed on 28 January 2027:

```
Deprecation: Sat, 01 Aug 2026 00:00:00 GMT
Sunset: Thu, 28 Jan 2027 00:00:00 GMT
Link: <https://docs.getcargo.ai/api-reference/versioning>; rel="deprecation"
```

Do not keep calling an operation after its `Sunset` date. Prefer its
replacement, named in the OpenAPI description of that operation, as soon as
`Deprecation` appears.

## Current versions

| Version | Path  | Status  | Sunset |
| ------- | ----- | ------- | ------ |
| v1      | `/v1` | Current | None   |

There is no v0 and no unversioned REST surface. `/v1` is the first public
version and it is not deprecated.


# Webhooks
Source: https://docs.getcargo.ai/api-reference/webhooks

Signed HTTP callbacks for tool batches, incoming HTTP listeners, and monitoring alerts.

Cargo webhooks are signed HTTP callbacks. Cargo POSTs JSON to a URL you control when a batch finishes, when a monitored tool fails, or when an external system pushes an event into a model.

## Batch and tool completion

When you create a tool batch you may pass `webhookUrl` and, optionally, `webhookSecret`:

```bash theme={null}
curl -X POST "https://api.getcargo.io/v1/tools/{tool_id}/batches?token={your_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/cargo-callback",
    "webhookSecret": "your-secret",
    "data": [
      {"company_domain": "acme.com"}
    ]
  }'
```

`webhookUrl` is optional. When set, results are POSTed there on completion. When `webhookSecret` is set, Cargo signs every delivery with HMAC-SHA256 in the `X-Cargo-Signature` header (`sha256=<hex>`). Verify the signature before trusting a delivery:

```ts theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

function isValidSignature(rawBody: string, secret: string, header: string) {
  const expected =
    "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}
```

See [Triggering a tool](/tools/triggering) for the rest of the batch API.

## Incoming HTTP listeners

The HTTP integration can **listen** for webhooks from an external system. Cargo issues a unique URL; a POST to that URL inserts or updates rows on a model and can enrol them in a play.

See [HTTP integration](/integration/http).

## Monitoring

Alerts and tool monitors can POST to your own systems on failure. See [Monitoring a tool](/tools/monitoring).


# Create environment variable
Source: https://docs.getcargo.ai/api-reference/workspace-management--environment-variables/create-environment-variable

https://api.getcargo.io/openapi.json post /workspaceManagement/env-vars
Create a workspace environment variable, injected into every worker, app and agent (POST /workspaceManagement/env-vars).



# List environment variables
Source: https://docs.getcargo.ai/api-reference/workspace-management--environment-variables/list-environment-variables

https://api.getcargo.io/openapi.json get /workspaceManagement/env-vars
List workspace environment variables. Secret values are returned as null (GET /workspaceManagement/env-vars).



# Remove environment variable
Source: https://docs.getcargo.ai/api-reference/workspace-management--environment-variables/remove-environment-variable

https://api.getcargo.io/openapi.json delete /workspaceManagement/env-vars/{uuid}
Remove a workspace environment variable (DELETE /workspaceManagement/env-vars/{uuid}).



# Update environment variable
Source: https://docs.getcargo.ai/api-reference/workspace-management--environment-variables/update-environment-variable

https://api.getcargo.io/openapi.json patch /workspaceManagement/env-vars/{uuid}
Update a workspace environment variable (PATCH /workspaceManagement/env-vars/{uuid}).



# Abort multipart upload
Source: https://docs.getcargo.ai/api-reference/workspace-management--files/abort-multipart-upload

https://api.getcargo.io/openapi.json post /workspaceManagement/files/multipart/abort
Abort an in-progress multipart upload and discard its parts (POST /workspaceManagement/files/multipart/abort).



# Complete multipart upload
Source: https://docs.getcargo.ai/api-reference/workspace-management--files/complete-multipart-upload

https://api.getcargo.io/openapi.json post /workspaceManagement/files/multipart/complete
Assemble the uploaded parts into the final S3 object (POST /workspaceManagement/files/multipart/complete).



# Create multipart upload
Source: https://docs.getcargo.ai/api-reference/workspace-management--files/create-multipart-upload

https://api.getcargo.io/openapi.json post /workspaceManagement/files/multipart/create
Start a direct-to-S3 multipart upload and return the target key and upload id (POST /workspaceManagement/files/multipart/create).



# Fetch file
Source: https://docs.getcargo.ai/api-reference/workspace-management--files/fetch-file

https://api.getcargo.io/openapi.json get /workspaceManagement/files/fetch
Fetch file data (GET /workspaceManagement/files/fetch).



# List file columns
Source: https://docs.getcargo.ai/api-reference/workspace-management--files/list-file-columns

https://api.getcargo.io/openapi.json get /workspaceManagement/files/listColumns
List columns from a file (GET /workspaceManagement/files/listColumns).



# Sign multipart upload part
Source: https://docs.getcargo.ai/api-reference/workspace-management--files/sign-multipart-upload-part

https://api.getcargo.io/openapi.json post /workspaceManagement/files/multipart/sign
Return a presigned URL to upload a single part directly to S3 (POST /workspaceManagement/files/multipart/sign).



# Upload file
Source: https://docs.getcargo.ai/api-reference/workspace-management--files/upload-file

https://api.getcargo.io/openapi.json post /workspaceManagement/files/upload
Upload a file to the workspace as multipart/form-data with a 'file' field (POST /workspaceManagement/files/upload).



# Create folder
Source: https://docs.getcargo.ai/api-reference/workspace-management--folders/create-folder

https://api.getcargo.io/openapi.json post /workspaceManagement/folders
Create a new folder (POST /workspaceManagement/folders).



# Get folder
Source: https://docs.getcargo.ai/api-reference/workspace-management--folders/get-folder

https://api.getcargo.io/openapi.json get /workspaceManagement/folders/{uuid}
Get a folder by UUID (GET /workspaceManagement/folders/{uuid}).



# List folders
Source: https://docs.getcargo.ai/api-reference/workspace-management--folders/list-folders

https://api.getcargo.io/openapi.json get /workspaceManagement/folders/list
List all folders (GET /workspaceManagement/folders/list).



# Remove folder
Source: https://docs.getcargo.ai/api-reference/workspace-management--folders/remove-folder

https://api.getcargo.io/openapi.json delete /workspaceManagement/folders/{uuid}
Remove a folder (DELETE /workspaceManagement/folders/{uuid}).



# Update folder
Source: https://docs.getcargo.ai/api-reference/workspace-management--folders/update-folder

https://api.getcargo.io/openapi.json put /workspaceManagement/folders/{uuid}
Update a folder (PUT /workspaceManagement/folders/{uuid}).



# Create report
Source: https://docs.getcargo.ai/api-reference/workspace-management--reports/create-report

https://api.getcargo.io/openapi.json post /workspaceManagement/reports
Submit a user report (feedback) for the current workspace (POST /workspaceManagement/reports).



# Check role exists by slug
Source: https://docs.getcargo.ai/api-reference/workspace-management--roles/check-role-exists-by-slug

https://api.getcargo.io/openapi.json get /workspaceManagement/roles/existsBySlug
Check if a role exists by its slug (GET /workspaceManagement/roles/existsBySlug).



# Create role
Source: https://docs.getcargo.ai/api-reference/workspace-management--roles/create-role

https://api.getcargo.io/openapi.json post /workspaceManagement/roles
Create a custom role (POST /workspaceManagement/roles).



# Get role
Source: https://docs.getcargo.ai/api-reference/workspace-management--roles/get-role

https://api.getcargo.io/openapi.json get /workspaceManagement/roles/{uuid}
Get a role by UUID (GET /workspaceManagement/roles/{uuid}).



# List roles
Source: https://docs.getcargo.ai/api-reference/workspace-management--roles/list-roles

https://api.getcargo.io/openapi.json get /workspaceManagement/roles
List all roles (GET /workspaceManagement/roles).



# List roles
Source: https://docs.getcargo.ai/api-reference/workspace-management--roles/list-roles-1

https://api.getcargo.io/openapi.json get /workspaceManagement/roles/list
List all roles (GET /workspaceManagement/roles/list).



# Remove role
Source: https://docs.getcargo.ai/api-reference/workspace-management--roles/remove-role

https://api.getcargo.io/openapi.json delete /workspaceManagement/roles/{uuid}
Remove a custom role (DELETE /workspaceManagement/roles/{uuid}).



# Update role
Source: https://docs.getcargo.ai/api-reference/workspace-management--roles/update-role

https://api.getcargo.io/openapi.json patch /workspaceManagement/roles/{uuid}
Update a custom role's permissions (PATCH /workspaceManagement/roles/{uuid}).



# Upsert session
Source: https://docs.getcargo.ai/api-reference/workspace-management--sessions/upsert-session

https://api.getcargo.io/openapi.json post /workspaceManagement/sessions
Create or update a session (POST /workspaceManagement/sessions).



# Acquire state lock
Source: https://docs.getcargo.ai/api-reference/workspace-management--states/acquire-state-lock

https://api.getcargo.io/openapi.json post /workspaceManagement/states/{uuid}/lock/acquire
Take the deploy lock on a state. Refused while another run holds an unexpired lock, unless forced (POST /workspaceManagement/states/{uuid}/lock/acquire).



# Create state
Source: https://docs.getcargo.ai/api-reference/workspace-management--states/create-state

https://api.getcargo.io/openapi.json post /workspaceManagement/states
Create a deploy state for a CDK project. The CLI writes the returned uuid into the repo's cargo.state.json (POST /workspaceManagement/states).



# Get state
Source: https://docs.getcargo.ai/api-reference/workspace-management--states/get-state

https://api.getcargo.io/openapi.json get /workspaceManagement/states/{uuid}
Get a deploy state by UUID, including its contents (GET /workspaceManagement/states/{uuid}).



# List states
Source: https://docs.getcargo.ai/api-reference/workspace-management--states/list-states

https://api.getcargo.io/openapi.json get /workspaceManagement/states/list
List every deploy state in the workspace (GET /workspaceManagement/states/list).



# Release state lock
Source: https://docs.getcargo.ai/api-reference/workspace-management--states/release-state-lock

https://api.getcargo.io/openapi.json post /workspaceManagement/states/{uuid}/lock/release
Release the deploy lock this run holds on a state (POST /workspaceManagement/states/{uuid}/lock/release).



# Update state
Source: https://docs.getcargo.ai/api-reference/workspace-management--states/update-state

https://api.getcargo.io/openapi.json put /workspaceManagement/states/{uuid}
Replace a deploy state's contents. Refused when the version has moved on or another run holds the lock (PUT /workspaceManagement/states/{uuid}).



# Create token
Source: https://docs.getcargo.ai/api-reference/workspace-management--tokens/create-token

https://api.getcargo.io/openapi.json post /workspaceManagement/tokens
Create a new API token (POST /workspaceManagement/tokens).



# List tokens
Source: https://docs.getcargo.ai/api-reference/workspace-management--tokens/list-tokens

https://api.getcargo.io/openapi.json get /workspaceManagement/tokens/list
List all API tokens (GET /workspaceManagement/tokens/list).



# Remove token
Source: https://docs.getcargo.ai/api-reference/workspace-management--tokens/remove-token

https://api.getcargo.io/openapi.json delete /workspaceManagement/tokens/{uuid}
Remove an API token (DELETE /workspaceManagement/tokens/{uuid}).



# Update token
Source: https://docs.getcargo.ai/api-reference/workspace-management--tokens/update-token

https://api.getcargo.io/openapi.json patch /workspaceManagement/tokens/{uuid}
Update an API token (PATCH /workspaceManagement/tokens/{uuid}).



# Create user
Source: https://docs.getcargo.ai/api-reference/workspace-management--users/create-user

https://api.getcargo.io/openapi.json post /workspaceManagement/users
Create a new user in the workspace (POST /workspaceManagement/users).



# Get current user
Source: https://docs.getcargo.ai/api-reference/workspace-management--users/get-current-user

https://api.getcargo.io/openapi.json get /workspaceManagement/users/current
Get the current user in the workspace (GET /workspaceManagement/users/current).



# List users
Source: https://docs.getcargo.ai/api-reference/workspace-management--users/list-users

https://api.getcargo.io/openapi.json get /workspaceManagement/users/list
List all users in the workspace (GET /workspaceManagement/users/list).



# Remove user
Source: https://docs.getcargo.ai/api-reference/workspace-management--users/remove-user

https://api.getcargo.io/openapi.json delete /workspaceManagement/users
Remove a user from the workspace (DELETE /workspaceManagement/users).



# Remove user permission
Source: https://docs.getcargo.ai/api-reference/workspace-management--users/remove-user-permission

https://api.getcargo.io/openapi.json delete /workspaceManagement/users/{userUuid}/permissions
Remove a permission from a user (DELETE /workspaceManagement/users/{userUuid}/permissions).



# Update user
Source: https://docs.getcargo.ai/api-reference/workspace-management--users/update-user

https://api.getcargo.io/openapi.json put /workspaceManagement/users/{uuid}
Update a user (PUT /workspaceManagement/users/{uuid}).



# Upsert user permissions
Source: https://docs.getcargo.ai/api-reference/workspace-management--users/upsert-user-permissions

https://api.getcargo.io/openapi.json post /workspaceManagement/users/permissions
Grant permissions on a resource to users (POST /workspaceManagement/users/permissions).



# Create workspace
Source: https://docs.getcargo.ai/api-reference/workspace-management--workspaces/create-workspace

https://api.getcargo.io/openapi.json post /workspaceManagement/workspaces
Create a new workspace (POST /workspaceManagement/workspaces).



# Get current workspace
Source: https://docs.getcargo.ai/api-reference/workspace-management--workspaces/get-current-workspace

https://api.getcargo.io/openapi.json get /workspaceManagement/workspaces/current
Get the current workspace (GET /workspaceManagement/workspaces/current).



# Get workspace login providers
Source: https://docs.getcargo.ai/api-reference/workspace-management--workspaces/get-workspace-login-providers

https://api.getcargo.io/openapi.json get /workspaceManagement/workspaces/loginProviders
Get the login providers for a workspace (GET /workspaceManagement/workspaces/loginProviders).



# List workspaces
Source: https://docs.getcargo.ai/api-reference/workspace-management--workspaces/list-workspaces

https://api.getcargo.io/openapi.json get /workspaceManagement/workspaces/list
List all workspaces (GET /workspaceManagement/workspaces/list).



# Update current workspace
Source: https://docs.getcargo.ai/api-reference/workspace-management--workspaces/update-current-workspace

https://api.getcargo.io/openapi.json put /workspaceManagement/workspaces/current
Update the current workspace (PUT /workspaceManagement/workspaces/current).



# Changelog
Source: https://docs.getcargo.ai/changelog

Week-by-week summary of new features, integrations, and improvements

Stay up to date with the latest changes to Cargo. This page covers the main updates shipped between **February and September 2026**.

***

## September 2026

<AccordionGroup>
  <Accordion title="Week of Sep 7–13" icon="calendar">
    **New features**

    * **`cargo-ai cdk` is now `cargo-ai project`** -- the command group that defines your workspace in a repo is named after what it makes. `cargo-ai cdk` keeps working as an alias, so nothing you have written down needs changing, and the TypeScript you import is still `@cargo-ai/cdk`

    **Integrations**

    * **Find email** -- each found address is now verified with ZeroBounce instead of Enrichley, including catch-all domains when that option is on
  </Accordion>

  <Accordion title="Week of Aug 31 – Sep 6" icon="calendar">
    **New features**

    * **Claude Code agents** -- Claude Code is now a runtime you pick on an agent release, alongside a repository, instead of a nested code capability. Deploy the agent from the checkout it should work on and the CDK binds the repository for you — owner, name, default branch and the project's directory come from the git remote, with the GitHub connector taken from the project — so `repository` only has to be written when the agent works on some other repo. The sandbox reaches any public API rather than only Cargo, npm and GitHub, and the agent's own shell, read and edit calls render as real cards in the chat with the command, its output and its exit code
    * **`cargo-ai ask`** -- a chat in your terminal, running Claude Code against the working copy on disk, so it reads and edits the files you already have. `ask "…"` opens with a first message, `--continue` resumes the last chat, `--print` runs a single turn as JSON, and typing prose into the command palette sends it here. Anything that touches the machine asks for approval first, the spinner names the tool that is running, and a stalled turn recovers into a new session instead of dropping you back at the shell. CLI chats are their own kind of activity in the app
    * **Email-driven agents** -- an agent can now be woken by its own mail: the first `sendEmail` from a chat binds it to that thread, and a later open, click, reply, bounce or unsubscribe starts the next turn in every chat on the thread. The agent reads the history with a new `listEmailEvents` action and ends the conversation for good with a close-chat tool, so a follow-up sequence stops when it should. Native triggers are typed in the CDK through `agentNativeTrigger`, and an event no longer has to wait out a pending heartbeat before it is answered
    * **Connect a domain you already own** -- Settings > Domains gains Connect domain next to Buy domain: publish the TXT record it shows you and the domain verifies itself, at no cost, instead of only being able to send from a name bought through Cargo. Mailboxes on a connected domain are not available yet
    * **Capabilities on MCP servers** -- a workspace MCP server can expose built-in abilities such as web search and workspace context as tools of its own, set from the server editor, the API, the CLI or `defineMcpServer({ capabilities: [...] })`. Web search no longer needs a chat behind it, so it works over MCP
    * **Home as one setup path** -- the app's Home is a single numbered sequence — install the CLI, sign in, create the project, add a cookbook, read the plan, deploy — in a terminal flavour and a coding-agent flavour, and picking a cookbook rewrites every command below it. The workspace panel counts all six deployable resources and links to Traces and Alerts
    * **`cdk init` sets up git and GitHub** -- after the project is written, init runs `git init`, offers to create a private GitHub repository, and offers to connect GitHub to Cargo and write the connector file, so the next steps only list what is actually left to do
    * **`cargo-ai book-demo`** -- open the same booking form as Talk to sales from the terminal, with your account email prefilled; `--no-open` prints the URL for scripts and agents

    **Integrations**

    * **X** -- `getFollowers` and `getFollowing` read up to 75,000 accounts in a single call, up from 10,000. Every people-returning action returns handle, name, location, avatar and account creation date again, after X moved those fields in its payload
    * **ChatGPT** -- connecting Cargo's MCP server from ChatGPT or Codex completes, since the per-connector OAuth callback they use is now accepted. Every platform MCP tool advertises an output schema and returns structured content, and run, batch and list responses carry the result rather than internal debug payloads
    * **Anthropic** -- an `instruct` call with web search returns the whole answer instead of the fragment left after the last citation
    * **SendGrid** -- `sendEmail` fills the variables of a dynamic template again, rather than sending the template blank
    * **Detect job change** -- the action declares its output, so `job_change_status` and the person's fields can be picked in a downstream node

    **Improvements**

    * `query_models` over MCP takes a read-only `SELECT` across `dataset.model` references, so a client can count, filter and join instead of paging a whole model through the tool. `modelUuid` and `offset` are gone, and `query` is required
    * An MCP session left idle between calls stays open instead of failing the next one with a closed connection
    * An agent that queries a model with timestamp or date columns carries on to the next step instead of failing on the result
    * Asking an agent to analyse a file no longer puts the chat into an error state
    * Hosted app builds run to the full 18-minute budget instead of being killed at five minutes and reported as an internal error with no build log
    * `cargo-cdk plan`, `check` and `deploy` work from any subdirectory of the project, and `deploy` stops before applying when a resource still needs a `secret()` that is missing from your `.env`
    * Deploying a `defineMailbox` no longer waits for the mailbox to become active, so a graph deploys while the mailbox is still pending
    * HTML written by an agent arrives as formatted mail instead of visible tags
    * An agent draft saves when no model provider is set, which is the normal state for a Claude Code agent
    * A play on a watched-records trigger starts its dependent plays once the batch finishes
    * An action config pinned to a number on a release is enforced on the agent's tool schema, so the model cannot ask for a different value
    * Chats and runs with nothing in flight are labelled Idle rather than spinning, and the Generating filter matches only what is really generating
    * The Activity field on Wait for email event is a set of radio options again instead of an expression input
    * Native actions no longer show as unknown icons in the agents list, and the Tools and Integrations columns are both called Actions
    * Running a node through the API requires workflow write permission, so a viewer can no longer execute one
    * Installing Cargo from a coding agent is four commands from a guide served at `api.getcargo.io/INSTALL.md`; the `install.sh` bootstrap that wrote into your Claude Code config is retired
    * Adding a cookbook ends on a setup checklist naming what to look up in the workspace and what only you can answer, and its scripts are installed under `scripts/<name>/`
  </Accordion>
</AccordionGroup>

## August 2026

<AccordionGroup>
  <Accordion title="Week of Aug 24–30" icon="calendar">
    **New features**

    * **Platform MCP server** -- connect ChatGPT, Claude or Cursor to `mcp.getcargo.io/mcp` and operate the whole workspace without publishing a server of your own: find, price and execute any action, run tools, ask agents, query a model's records, list plays, runs and connectors, and check credit usage. If you have a Cargo connector, enrichment and search tools come with it. The server sends a client its operating instructions on connect, so an assistant knows how the tools fit together with nothing to install, and `cargo-ai mcp` bridges it with no `--server`
    * **Workspace context over MCP** -- a connected client reads the playbooks, ICP definitions and rubrics your workspace keeps as context, through map, browse, search and read calls, so it answers from what your team actually wrote instead of what the model assumes. Read only, with no write, edit or shell access
    * **A CLI that opens on what you want to do** -- running `cargo-ai` at a terminal signs you in, lands you in a workspace and offers a destination: open a coding agent, run the guided demo, scaffold a project, or explore. Returning users get a searchable command palette where an option that wants an id offers the workspace's own rows, an option with a fixed set offers a menu, and a table can be narrowed in place with the filters the command already declares. Setup problems print the command that fixes them. The whole flow also runs headless with flags, and anything non-interactive behaves exactly as before
    * **Connectors from the CLI** -- `cargo-ai connection connector create` and `update` open the real connection form in a browser, handle the OAuth consent there, then hand you back to the terminal on a done screen, and `cargo-ai cdk add connector <slug>` also writes the connector file and binds it to your project state. Defining an OAuth integration in code no longer needs a manual detour through the app
    * **`cargo-cdk info`** -- the resolved project on one screen and offline: every resource in dependency order, the file it was declared in, whether it is new, live, draft or orphaned, what it depends on, and any problem blocking a deploy. `--json` emits the whole report
    * **Cookbooks in an existing project** -- `cargo-cdk catalog list`, `search` and `view` browse the cookbook catalog and `cargo-cdk add cookbook/<name>` installs one into a project you already have, instead of only into an empty directory. `cdk init` is interactive, takes `--cookbook`, and seeds your company context from your domain
    * **Wait for email event** -- a new native action holds a play until an open, click, reply or unsubscribe lands anywhere on the thread of an email you sent, or until the timeout you set
    * **Mailboxes on members** -- attach mailboxes to a revenue-organization member, from member settings, from `defineMember` in the CDK, or with `--mailbox-uuids` on the CLI. Each mailbox belongs to one member

    **Integrations**

    * **OpenAI** -- added the GPT-5.6 family, Sol, Terra and Luna, at the top of the model picker
    * **Surfe** -- new find person by email action, returning name, company, job title, country and LinkedIn URL
    * **LinkedIn** -- profile enrichment returns country as a name rather than a code, a profile with no location enriches instead of failing, and a company join date is derived from the whole run at that company. Post search accepts company IDs again, and the extension reconnects its identity on every sync
    * **AI Ark** -- gateway timeouts are retried for up to three attempts instead of failing the run, and an exhausted retry reports a short error rather than the provider's raw response
    * **Google Sheets** -- accented column headers are normalized, so a sheet that uses them syncs instead of failing
    * **HubSpot** -- sequence enrollment accepts numeric IDs
    * **Lusha** -- a node fails with the reason when the Lusha account is out of credits, instead of reporting an empty result
    * **Explorium** -- saving listen events skips ids the provider does not match, rather than failing the save

    **Improvements**

    * Plays and tools deployed from the CLI or the CDK are laid out automatically, so a graph written in code opens readable in the editor
    * `orchestration action list` returns a typed credit price for every billed action, natives included, showing whether it is fixed, metered per unit or sold in packages, and documenting that a fixed cost adds to the metered rate rather than replacing it
    * `orchestration action get-output-schema` accepts the same action object `action list` hands back, plus `--data` for the inputs that decide the shape, so the examples in its own help work as written
    * An email open is no longer recorded for a security scanner or for a pixel fetched within ten seconds of sending, so a wait-on-open never fires on a prefetch
    * Filter values on Match record and Search records nodes open in expression mode, so `/` shows the previous node's values
    * Renaming a node in the editor keeps the custom name when you click its label
    * Exporting run outputs completes when one stored object is not valid JSON, instead of failing the whole export
    * Connecting an MCP server that authenticates with `client_secret_basic` works
    * API token secrets are masked to the last four characters with reveal and copy, and the action docs, MCP server and ingest pages point at an existing token instead of minting a "Quick access" one
    * The Mailboxes list stops showing every mailbox as updated a minute ago while replies sync
    * Create and Save sit in a full-width footer on the connector, model, tool, play, worker, app and agent edit screens
  </Accordion>

  <Accordion title="Week of Aug 17–23" icon="calendar">
    **New features**

    * **Mailboxes** -- provision a fleet of sending mailboxes on a domain you own, warm them up toward a 40-a-day target, and send from a play, a tool or an agent with the new `sendEmail` action, which paces itself to whatever that mailbox's allowance is on the day. Every message carries one-click unsubscribe, opt-outs land on a suppression list checked on every send, and mailboxes are billed monthly
    * **Custom roles** -- Settings > Roles lets an admin build a role from the same per-domain Disabled / Read / Read & write matrix as API tokens, then assign it to members. The four built-in roles are unchanged
    * **Remote MCP clients over OAuth** -- ChatGPT, Claude and Cursor authorize against Cargo itself, so connecting one is a consent screen instead of a pasted token, and an admin can see every connected app on the MCP server page and revoke it. Agents find the server from a card published at `/.well-known/mcp`
    * **Analytics and logs for hosted apps and workers** -- an Analytics tab on an app lists ingested events and a Logs tab on a worker lists its runtime output, both filterable by search, kind or level and date range. Every worker invocation is also recorded as a trace, with the worker's console output under its span
    * **Agent-ready REST API** -- every 4xx and 5xx returns a typed error body, every operation carries a stable id, rate-limit headers ride on every `/v1` response including 401s, writes accept an `Idempotency-Key` so a retried request replays rather than duplicating, and long-running creates return `202 Accepted` with a `Location` to poll. The versioning and deprecation policy is published alongside the reference
    * **Synchronous action execution** -- `waitUntilFinished` on action execute and execute-batch holds the request until the run or batch reaches a terminal status, up to five minutes, and returns the finished run with its context. Anything slower comes back as a 408 carrying the run, so you can keep polling

    **Integrations**

    * **HubSpot** -- run a Cargo tool from inside HubSpot, either through the new Run Cargo tool workflow action, which enrols a record and reports back once the run finishes, or from a Cargo tools card pinned to a contact or company. Reconnect your HubSpot connector to pick up the scope the workflow callback needs
    * **Attio** -- new merge action, combining two records into one through Attio's record merge endpoint
    * **LinkedIn** -- post extraction takes a limit of 20 to 100 posts and returns them in a single pass, which restores extraction after the provider dropped the pagination it relied on. Backfilling further back than that limit is no longer possible
    * **Sillage** -- signal detection advances past each batch instead of re-fetching and re-billing the same signals every hour, a persona saved without a location is caught on the form with a readable message instead of failing the model, and copying a listen-signals model gives the copy its own workspace

    **Improvements**

    * Runs, records, spans and chats have a search box matching on title, id and, for spans, the execution error, with `--search` on the matching CLI commands and no `%` wildcards to write
    * `--is-enabled false` and every other boolean CLI flag mean what they say, instead of being read as the flag on its own
    * Deleting records no longer requires available credits, so a workspace over quota can still clean up
    * Model records larger than 3 MiB are rejected with a clear error when written, instead of failing the batch further down
    * Large warehouse-backed model and segment pages load without exhausting query memory
    * A script node that finished successfully no longer reports itself as failed
    * Clicking anywhere on a row in the Plays, Agents, Apps, Tools, Workers, Models, Alerts, MCP servers and Files lists opens it
    * Observe sits above Connect in the workspace sidebar
    * Tool cards no longer show a credit range of "max. NaN"
    * Workspace creation is capped at three per user per day
    * `cargo-ai manifest add` is removed: cookbook folders now ship as skills a coding agent places in your project, and `cargo-ai cdk init --from` stays as a plain scaffold
  </Accordion>

  <Accordion title="Week of Aug 10–16" icon="calendar">
    **New features**

    * **JavaScript models** -- `defineScript` fills a model from code you write in the CDK: the script runs in a sandbox on every sync, reads its own encrypted secrets from the model's `env`, and returns the rows that become the table, so anything you can reach in code becomes a model
    * **Node graph diagrams** -- `cargo-ai orchestration node diagram` draws a play, tool, release or run as a Mermaid flowchart or as ASCII for a terminal, marking the steps that bill, the fallback paths, and any node unreachable from `start`. It runs nothing and costs no credits
    * **Models and files as agent capabilities** -- attach as many models and files to an agent as you like without growing its tool list, and read a file exactly through new list, search and read calls instead of only searching it as a vector. Bulk-allowed actions are now one tool taking an `items` array, and a single item comes back as a record rather than a one-row CSV
    * **Custom column writes** -- the Model insert, update and upsert nodes map custom columns alongside original ones, so writing one no longer needs a node of its own, and `POST /storage/columns/insertCustomValues` and `cargo-ai storage column insert-custom-values` do the same from the API and the CLI
    * **Unattended payment methods** -- an agent can put a card on file with nobody watching, through a link that opens on the card form itself or by passing a payment method tokenized elsewhere. A card that cannot be charged is reported when you add it, with the issuer's decline reason, instead of at the next renewal
    * **Action reference in the app** -- Connect > Actions lists native actions such as `modelSearch`, `modelAsk`, `scoring` and `python` alongside agents, tools and integration actions, and documents every one of them through the same execute endpoints, with a cURL, `@cargo-ai/api` and `cargo-ai` switcher on each snippet
    * **Browserless setup for coding agents** -- `npx skills add getcargo.ai` or `docs.getcargo.ai` installs the Cargo skill bundle, `install.sh` takes `CARGO_EMAIL` and `CARGO_CODE` to create the account and sign in with no browser at any point, and both domains serve `/llms-full.txt`

    **Integrations**

    * **Datagma** -- new enrich person action keyed on a LinkedIn URL or a professional email, plus a second one that resolves a profile from a personal email address
    * **Apollo** -- runs first in the Find email and Find LinkedIn URL from email waterfalls, and a new Find LinkedIn company URL from domain tool ships the full provider waterfall
    * **Reverse Contact** -- moved to the provider's V2 API, which restores every action. Reconnect with a V2 key; keys issued for V1 no longer authenticate
    * **Wiza** -- enrichment waits for the reveal to finish, so a profile it does find is no longer reported as a miss, and a connector left without an API key says so instead of reporting itself connected
    * **Sales Navigator** -- a run that names one of your own LinkedIn users spends that seat's allowance instead of being metered against the shared pool quota
    * **HubSpot** -- a private-app token is verified when you save the connection, and the merge action accepts numeric primary IDs
    * **Custom integrations** -- a worker outage no longer wipes a connector's registered actions, since the last good manifest is served until the worker recovers. Valid extractor responses are accepted, and a webhook record that leaves a field empty still ingests
    * **FullEnrich** -- reverse email lookup completes on a webhook
    * **CompanyEnrich** -- nothing is billed when the lookup finds nothing
    * **Metabase** -- the column autocomplete accepts a numeric question id

    **Improvements**

    * Runs start faster when many runs are already open
    * `cargo-ai orchestration run download` takes `--uuids` to export a specific set of runs, and `--is-finished` is accepted again on run list, count and download
    * A failed model sync or run reports the underlying error instead of a generic message
    * Filter builders label the second button "Add group" once a group exists, and a saved segment hides Reset | Update after you update it
    * The run, node and batch inspectors stay open through play, tool and agent redirects
    * Nested groups are rejected on import, validate and deploy, with a clear error
    * Signing in works where the home directory is read-only, honouring `CARGO_CONFIG_DIR` and `XDG_CONFIG_HOME`
  </Accordion>

  <Accordion title="Week of Aug 3–9" icon="calendar">
    **New features**

    * **Traces** -- a new Traces section under Observe: filter traces by trigger, status and date, then open one as a flame graph, a waterfall or a span list, with the inputs, outputs and config of the selected node alongside it
    * **Alerts** -- schedule an alert on spans, on whole runs, on read-only SQL against your warehouse, or on a model's own health (record count, share of a filter, freshness since the last sync, last sync duration), and have it notify through Slack, Teams, Resend, SendGrid or an HTTP call
    * **Batch health alerts run any action** -- a play's batch health alert is no longer limited to one Slack message: it can fire any action, you can configure several, and each one now executes as a real run with its own trace, retries and credit accounting
    * **Sign in without a per-machine token** -- `cargo-ai login --email` signs you in with a code sent to your address, so it works from a CI container or an agent shell with no browser. The session covers every workspace you belong to instead of being pinned to one, `cargo-cdk` renews it from the same credential, and `cargo-ai logout` revokes it for good
    * **`cargo-ai billing add-payment-method`** -- attach a card from the CLI, the last workspace setup step that still required the dashboard
    * **`defineMember`** -- reference a revenue-org member by email in a CDK spec, so a repo that routes leads through territories is no longer pinned to one workspace's member ids
    * **`defineDomain`** -- register a sending domain through Cargo from a CDK spec and publish its DNS zone alongside it

    **Integrations**

    * **Metabase** -- new integration: run a saved question, run SQL against a connected database, search entities, sync a question's rows into a model, and hand an agent Metabase's own MCP tools. An admin must enable the MCP server under Admin > AI > MCP first
    * **Replicas** -- new integration with a launch agent action that runs a coding agent in a cloud workspace and returns its branches, diffs and pull requests to the next node
    * **Devin** -- new integration with a launch agent action that returns Devin's structured output and pull requests
    * **AI Ark** -- new enrich company action, keyed on a domain or LinkedIn URL at 0.01 credits, plus country and financial fields on company records and a search limit that shows the default you get
    * **LinkedIn and Sales Navigator** -- teammates who synced their session through the Chrome extension now show up as Revenue Organization members, so a capacity can cap their connection requests, messages and profile visits the way it caps CRM records. The Linkedin Users fields now link to the extension
    * **GitHub** -- connections request the scopes needed to reach private organization repositories, so they appear in the repository picker and the code capability can clone them and open pull requests. Reconnect an existing GitHub connector to pick this up

    **Improvements**

    * Sales Navigator usage is metered per workspace against quota buckets, 1,000 requests per bucket per rolling 24 hours, so one workspace's volume no longer eats the allowance everyone shares
    * Exporting run and record outputs streams to storage, so large exports complete instead of failing
    * Warehouse queries are generated without redundant work, cutting the time segment filters, record lookups and record counts spend on your warehouse
    * Opening a play or a tool no longer freezes the tab
    * Intermittent "failed to fetch" errors on long-lived browser sessions are fixed
    * The run, node, batch, chat, message and file inspectors open in a side drawer, so they stack cleanly instead of dropping a dialog over the trace panel
    * Writing to a column a model does not have is rejected naming the unknown and the available columns, instead of succeeding and silently dropping the value
    * Segment create and update return the synced record count and sync time, instead of always reporting zero records
    * JavaScript script nodes accept a `result` variable as their output, matching Python nodes, and the editor ships with a starter example
    * Creating a batch from a play's generated segment is refused with a message that says so, instead of reporting no records
    * Agent descriptions longer than 255 characters save
    * A fixed-price action bills nothing when it finds nothing, so a miss on AI Ark enrichment is no longer charged as a hit
    * A model refresh that is already running reports itself as refreshing instead of failing with a lock error
    * Span search matches on the execution error message as well as the title
    * API tokens can be granted Observability, so a token can read workspace events and manage alerts
    * The workspace menu links to the Cargo status page
    * Phantombuster models backfill an agent's full run history instead of only its most recent containers
    * FullEnrich requests are paced instead of released in bursts, which stops the 429s and the enrichment requests that could never be satisfied
    * Sillage connections surface configuration problems as readable rejections, sync when a top account has no removable identifier, and stop their agents when a model resolves no account
    * LinkedIn matched audiences are created with a valid source platform
    * The webhook token alert is hidden on native models
    * Workspaces with very large numbers of models sync faster
  </Accordion>
</AccordionGroup>

## July 2026

<AccordionGroup>
  <Accordion title="Week of Jul 27 – Aug 2" icon="calendar">
    **New features**

    * **`cdk deploy --draft`** -- stage plays, tools, agents, workers, and apps as unpublished drafts, test them, then publish with a plain `cdk deploy`
    * **Managed play on/off switch** -- `definePlay` takes `isEnabled`, so a play ships enabled or held off from code instead of needing a manual toggle
    * **Model config redeploys** -- a deploy that changes a model's config relaunches a reset run, so the data is rebuilt under the new config
    * **Action search and `doctor`** -- `cargo-ai connection action search` finds any integration action by keyword, and `cargo-ai doctor` reports CLI version, credentials, and API reachability in one command
    * **Project `.env` auto-discovery** -- the CLI and CDK pick up `CARGO_API_TOKEN`, `CARGO_WORKSPACE_UUID`, and `CARGO_BASE_URL` from the nearest project `.env`, so a repo pinned to one workspace stays on it
    * **Snowflake statement timeout** -- set `statementTimeoutSeconds` on a Snowflake source to cancel runaway queries server-side
    * **Browser tab titles** -- tabs show the current page or entity name instead of "Cargo - App", and keep it when you filter or sort

    **Integrations**

    * **LinkedIn** -- new Enrich Post and Message Profile actions, new page followers, followers, and company viewers extractors, and post comment and reaction search now accepts a post URL
    * **AI Ark** -- new count people and count companies actions, searches paginate up to 2,000 records, and the Technologies and NAICS filters have searchable dropdowns
    * **Gemini** -- added the Gemini 3.6 Flash and 3.5 Flash-Lite models, with 3.6 Flash as the new default
    * **Apollo.io** -- clearer sequence options and contact mapping fields

    **Improvements**

    * Haiku is now priced at the small-model tier, 0.05 credits per 1K tokens
    * Agents default to a temperature of 1, so releases on current Anthropic models no longer error
    * Model schedules are validated against the extractor's minimum interval, instead of scheduling runs that can never do anything
    * Deleting a field from a CDK spec now clears it on the live resource, and a deploy creates resources or fails rather than silently binding to one it did not create
    * Model tables keep refreshing while a workspace is out of credits
    * Model search no longer waits behind a table refresh, so high-volume searches stop failing on lock timeouts
    * Sorting records on a column the model's table does not have is rejected with a clear message
    * You can sign in from a headless environment, such as a CI container or an agent session, through the device flow
    * Tool nodes report their real result when the final workflow node is not named `end`
    * A Sillage connection with no top accounts syncs instead of failing
  </Accordion>

  <Accordion title="Week of Jul 20–26" icon="calendar">
    **New features**

    * **Code capability** -- from an agent chat, delegate coding work on your own GitHub repository to a coding agent running in a sandbox, and get a pull request back
    * **Generate an output schema from a prompt** -- write the prompt, hit Generate, and the structured-output JSON schema is filled in for you
    * **Large file uploads** -- files upload straight to S3 in parallel parts, so multi-gigabyte CSVs no longer break mid-transfer
    * **Shareable model views** -- the selected segment, filters, sort, record limit, and visible columns live in the URL, so a refresh or a shared link restores the same view
    * **API token descriptions** -- tokens take an optional description, and the auto-created token is now "Quick access"
    * **Event-only entities** -- a company or person seen only in events now gets a row in unified Accounts and Contacts, so its joined columns resolve

    **Integrations**

    * **AI Ark** -- new integration with six actions and two extractors, covering search, profile enrichment, email and mobile lookup, and reverse lookup
    * **X (Twitter)** -- new connector with user, post, and search actions plus matching extractors
    * **BuiltWith** -- new enrichment integration with enrich domain and find websites by technology
    * **OpenRouter** -- new language-model provider, so agents can run any model OpenRouter fronts
    * **Parallel and Exa** -- billable with Cargo credits, so they run without a key of your own
    * **Apollo** -- expanded search, new people and organization extractors, and location autocomplete on company search and fetch
    * **Sillage** -- new fetch leads extractor and search leads action, signal agents in the extractor, and source columns on signals
    * **Dropcontact** -- find email now runs through async webhooks
    * **HubSpot** -- `isEmpty` and `isNotEmpty` filters, and properties whose internal name contains `___` are kept
    * **Surfe** -- fixed authentication and enrichment webhook handling
    * **Smartlead** -- fixed listen-events webhook registration and webhook deletion
    * **OpenAI** -- removed the invalid `gpt-5.5-mini` and `gpt-5.5-nano` models

    **Improvements**

    * `cdk plan` loads resources about 50x faster on a large workspace
    * Worker environment variables resolve at runtime, and secrets stay out of the deployed bundle
    * The enroll modal starts with no records selected
    * Each unification strength option explains what it does
    * Segment fetch and stream return records in a deterministic order
    * Run errors name the reason a run could not be created
    * Empty filter groups are rejected instead of matching everything
    * A tool release with no form fields is refused at deploy time
    * Number columns cast to dates infer their epoch unit
  </Accordion>

  <Accordion title="Week of Jul 13–19" icon="calendar">
    **New features**

    * **CDK manifests** -- new `cdk manifest init` and `cdk manifest add` commands to set up GTM repos
    * **Test before you deploy** -- run agents and workflows straight from your CDK project, plus `cdk check`, slug hints, and loop DX
    * **`cargo-ai mcp`** -- a stdio bridge that connects any MCP client to your Cargo MCP servers
    * **Local worker development** -- `npm run dev` in the worker SDK for a local dev loop
    * **Realtime computed columns** -- computed columns are evaluated on the fly for realtime plays
    * **Filtered watch schedules** -- watch schedules can now run on models with a config filter
    * **Download deployment source** -- grab the source of any hosting deployment from its dropdown
    * **Default API token** -- workspaces now surface a user-facing default token
    * **Per-reference unification** -- configure unification per reference, with account slug matching

    **Integrations**

    * **Anthropic** -- added the Claude Sonnet 5 model
    * **Salesforce** -- REST request and invoke flow actions
    * **Lemlist** -- CRM contact and company actions
    * **Company Enrich** -- Get Workforce and Lookup Person actions
    * **Slack** -- clearer agent message display

    **Improvements**

    * Token usage is now returned by OpenAI and Anthropic instruct actions
    * Chat renders every context capability tool invocation
    * Segment filters are validated against column types
    * The end node is now a regular node you can add and remove
    * Territory descriptions accept long-form text
  </Accordion>

  <Accordion title="Week of Jul 6–12" icon="calendar">
    **New features**

    * **`cdk pull`** -- generate `define*` source from a live workspace
    * **`cdk init --from`** -- scaffold a project from a cookbook repo on GitHub
    * **Models in the CDK** -- native object and unified models, unification, relationships, and typed `model.columns` accessors
    * **Typed action outputs** -- integration action outputs are typed in workflow codegen
    * **App capability** -- agents can edit a hosted app in a git-backed sandbox runtime
    * **Worker cron triggers** -- schedule workers, with custom-integration auto-detect and automatic Cargo API auth
    * **Export deployment source** -- download any deployment as a `tar.gz`
    * **`cargo-quickstart`** -- a guided first-run demo launched by the installer

    **Integrations**

    * **Sillage** -- new integration with a listen signals extractor
    * **Default connector per integration** -- pick which connector an integration uses by default

    **Improvements**

    * MCP tool calls no longer time out on long-running actions
    * Computed column DDL is idempotent and surfaces structured errors
    * Record creation returns a readable message on validation errors
    * Manual runs in the play editor no longer hang or spawn duplicate runs
  </Accordion>

  <Accordion title="Week of Jun 30 – Jul 5" icon="calendar">
    **New features**

    * **Cargo CDK** -- define your entire Cargo setup in code and deploy it, including capacities and territories
    * **Standalone `cargo-cdk` bin** -- run the CDK as its own command
    * **Single sign-on per workspace** -- enforce a login provider per workspace, with Okta SSO support
    * **Edit in editor** -- reopen a past run in the editor to reproduce and iterate on it
    * **Inline file viewer** -- preview files directly in the files library

    **Integrations**

    * **Surfe** -- new integration
    * **LinkedIn & Sales Navigator** -- expired identities are now flagged in connection pickers so you can reconnect

    **Improvements**

    * HTTP webhook triggers now support insert, update, and remove events
    * Renamed "Revenue Organization" to "Territories" across the product
    * Restrict workspace access to company email domains
    * Workers are now built from TypeScript source server-side
  </Accordion>
</AccordionGroup>

## June 2026

<AccordionGroup>
  <Accordion title="Week of Jun 23–29" icon="calendar">
    **New features**

    * **Parallel Create Task** -- new Parallel AI action with webhook support
    * **Smarter exports** -- exports now respect your row selection and use meaningful filenames

    **Integrations**

    * **Perplexity** -- now selectable as an agent model
    * **Salesforce** -- hosted MCP integration
    * **LinkedIn** -- new Extract Similar Companies action

    **Improvements**

    * Raised the HTTP Call action timeout to 6 minutes for slower endpoints
    * Faster, more reliable runs across the platform
  </Accordion>

  <Accordion title="Week of Jun 16–22" icon="calendar">
    **New features**

    * **Agent output evaluator** -- automatically grade and gate agent output quality
    * **Resumable batches** -- large runs batches now resume where they left off
    * **Workflow deploy diff** -- review changes before deploying a workflow
    * **Per-segment columns** -- your column selection now persists per segment

    **Integrations**

    * **HubSpot & Notion** -- dedicated MCP integrations
    * **LinkedIn** -- Extract Company Employees Insights action
    * **Sales Navigator** -- person and company search metrics
    * **Lemlist** -- inbox and task actions
    * **Bright Data** -- Facebook profile scraping and async social actions

    **Improvements**

    * Content permissions can now be granted per role
  </Accordion>

  <Accordion title="Week of Jun 9–15" icon="calendar">
    **New features**

    * **Workflow SDK** -- define workflows in code with TypeScript
    * **Domain management** -- buy and manage sending domains in-app, powered by the new Mailpool integration
    * **Cargo Forms** -- embeddable forms with a public form trigger
    * **Hosting previews** -- per-deployment preview URLs for apps and workers, plus custom domains
    * **Run date filters** -- filter runs by updated-after / updated-before

    **Integrations**

    * **Bright Data** -- Instagram, TikTok, Facebook, X, and YouTube scraping actions
    * **Salesloft** -- create notes on persons and accounts
    * **Anthropic** -- added the Claude Fable 5 model

    **Improvements**

    * Context files auto-fill missing title and description
  </Accordion>

  <Accordion title="Week of Jun 2–8" icon="calendar">
    **New features**

    * **Agents write to data models** -- agents can insert, update, upsert, and delete records
    * **Content library** -- files organized into a dedicated Content area with libraries
    * **Model relationships** -- link native object models together
    * **Expandable record view** -- richer record modal with model icons and a Canvas view toggle
    * **CLI update notifier** -- the CLI now tells you when a new version is available

    **Integrations**

    * **Parallel AI** -- new integration with Search and Extract actions
    * **Google Ads** -- Customer Match audiences
    * **Redshift** -- support for views in the fetch table extractor

    **Improvements**

    * Row-level filters on custom unification
    * Link-shortener domains are now blocked during unification for cleaner data
  </Accordion>
</AccordionGroup>

## May 2026

<AccordionGroup>
  <Accordion title="Week of May 26 – Jun 1" icon="calendar">
    **New features**

    * **Agent memory** -- agents can now retain memory across conversations
    * **Chat heartbeat** -- conversations auto-wake to continue long-running work
    * **Code interpreter & file attachments** -- improved code interpreter and file attachments in chat
    * **File search** -- search across your uploaded files
    * **Preview action outputs** -- see an action's output schema without running it
    * **Wait for completion** -- new option to wait for tool/agent steps to finish

    **Integrations**

    * **OpenAI & Anthropic** -- added GPT 5.5 / 5.3 and Claude Opus 4.8 models
  </Accordion>

  <Accordion title="Week of May 19–25" icon="calendar">
    **New features**

    * **Structured AI output** -- define a JSON schema for AI output at the release level
    * **Unification column selection** -- choose which columns to unify
    * **Human review in Slack** -- review items in Slack with an optional Edit button

    **Integrations**

    * **Airscale** -- personal email, reverse email, reverse phone, and Find People
    * **Smartlead** -- webhook events extractor
    * **HeyReach** -- list users for revenue organization sync

    **Improvements**

    * Integration models can now live inside model folders
    * Choose a default output type when creating AI messages
  </Accordion>

  <Accordion title="Week of May 12–18" icon="calendar">
    **New features**

    * **LinkedIn profile viewers** -- incremental viewers with a configurable extract limit

    **Integrations**

    * **Airscale** -- new integration with a phone lookup action
    * **Explorium** -- expanded business search filters
    * **NetSuite** -- improved field schema handling
  </Accordion>

  <Accordion title="Week of May 5–11" icon="calendar">
    **New features**

    * **Apps & Workers hosting** -- host apps and workers directly on Cargo
    * **Context files** -- new Context files and Context Agent
    * **Edit records inline** -- create and edit model records directly from the model view
    * **Monthly schedules** -- added an 'Every month' scheduling option
    * **Longer agent runs** -- raised the AI agent max steps from 30 to 100

    **Integrations**

    * **Marketo** -- new integration with Custom Objects support
    * **Mixpanel** -- EU data residency support
    * **Outreach** -- richer event attributes
    * **Cargo** -- prospect and business event triggers

    **Improvements**

    * Raised waterfall throughput for faster enrichment
  </Accordion>
</AccordionGroup>

## April 2026

<AccordionGroup>
  <Accordion title="Week of Apr 28 – May 4" icon="calendar">
    **New features**

    * **LinkedIn Matched Audiences** -- sync matched audiences via Polytomic
    * **LinkedIn profile viewers** -- fetch and extract profile viewers
    * **SQL exports** -- download query results directly
    * **Persistent filters** -- Logs and Agent Activities filters now persist in the URL

    **Improvements**

    * Renamed orchestration logs to "spans" for clarity
  </Accordion>

  <Accordion title="Week of Apr 21–27" icon="calendar">
    **New features**

    * **Scoped API tokens** -- create tokens with named, granular permissions
    * **Query your runtime data** -- run SQL over runs, batches, and records
    * **Easier CLI setup** -- CLI device-flow login and a one-line installer
    * **Workspace reports** -- submit feedback reports from your workspace

    **Integrations**

    * **Anthropic** -- added Claude Opus 7
    * **Cargo** -- Bombora intent topics enrichment
    * **LinkedIn** -- profile activity extraction

    **Improvements**

    * Promoted Claude Code as the primary install path
    * Raised the sync cap to 12k records for BigQuery and Snowflake
  </Accordion>

  <Accordion title="Week of Apr 14–20" icon="calendar">
    **New features**

    * **Instant record updates** -- record changes now apply immediately
    * **Concurrent runs limit** -- set a per-workspace concurrent runs limit
    * **Node status filter** -- filter model executions by node execution status

    **Integrations**

    * **OpenAI** -- added GPT 5.4 mini and GPT 5.4 nano models

    **Improvements**

    * Billing settings actions now respect write permissions
  </Accordion>

  <Accordion title="Week of Apr 7–13" icon="calendar">
    **New features**

    * **Tools are now "actions"** -- consistent terminology across the app
    * **Orchestration root nodes** -- with last-execution outputs
    * **Self-serve tier** -- new 1.5K credits/mo plan
  </Accordion>

  <Accordion title="Week of Mar 31 – Apr 6" icon="calendar">
    **New features**

    * **MCP resources & templates** -- resources support and reusable server templates for MCP
    * **Redesigned model list** -- grouped objects with active/inactive datasets
    * **Workspace logs view** -- see logs and execution timestamps across your workspace
    * **Signed batch webhooks** -- secret signing for batch completion webhooks

    **Integrations**

    * **Sales Navigator** -- company search metrics

    **Improvements**

    * Added unification mappings for official integrations
    * Renamed "Storage" to "Data Model"
    * Clearer CLI help text and a revamped sidebar
  </Accordion>
</AccordionGroup>

## March 2026

<AccordionGroup>
  <Accordion title="Week of Mar 24–30" icon="calendar">
    **New features**

    * **Record outputs export** -- export the output of individual records from workflow runs
    * **Date filters on runs** -- filter workflow run history by date range
    * **Monitoring webhooks** -- receive webhook notifications for workflow monitoring events

    **Integrations**

    * **Piloterr** -- added G2 product info endpoint integration
    * **Waterfall** -- added logging for waterfall webhooks

    **Improvements**

    * AI chats now use a table layout for better readability
    * Schedule display fixes
  </Accordion>

  <Accordion title="Week of Mar 17–23" icon="calendar">
    **New features**

    * **Community templates** -- browse and use community-contributed workflow templates
    * **Schedule on ingest model** -- schedule-based triggers now supported on ingest models
    * **Open tool/agent button** -- quickly jump to a tool or agent definition from the AI tools editor

    **Integrations**

    * **Email Bison** -- new integration with upsert lead action
    * **PhantomBuster** -- added fetch agent results action and UI schema
    * **LinkedIn** -- fixed post comment and reaction extraction
  </Accordion>

  <Accordion title="Week of Mar 10–16" icon="calendar">
    **New features**

    * **GPT-5.4 model support** -- added GPT-5.4 as an available language model
    * **Sales Navigator fetch accounts** -- new action to fetch account data from Sales Navigator with account-level filters
    * **Context resources** -- introduce contextual data resources for workflows
    * **Autocomplete search** -- search-on-change support for autocomplete fields across integrations

    **Integrations**

    * **Instantly** -- added search action
    * **Sales Navigator** -- account filters and extractor UUID support

    **Improvements**

    * Pricing page now shows enrichment credit details
    * Faster BigQuery and Snowflake downloads
    * Improved node validation
    * Improved model pause behavior
  </Accordion>

  <Accordion title="Week of Mar 3–9" icon="calendar">
    **New features**

    * **Integration MCP clients** -- integrations can now expose MCP-compatible tool clients
    * **Sales Navigator search limit** -- raised search leads limit to 25,000 records
    * **Release version validation** -- added validation for release versions

    **Integrations**

    * **Resend** -- new Resend API integration for transactional email
    * **Adyntel** -- new Adyntel integration
    * **DataFast** -- new DataFast integration with auto page view capture
    * **PhantomBuster** -- added fetch agent results action
    * **Firecrawl** -- added search endpoint
    * **Icypeas** -- added findPeople and findCompanies actions
    * **EnrichCRM** -- added getFunding action

    **Improvements**

    * Improved Sales Navigator search
    * Improved "let agent decide" mode
    * URL verification webhook support
  </Accordion>
</AccordionGroup>

## February 2026

<AccordionGroup>
  <Accordion title="Week of Feb 24 – Mar 2" icon="calendar">
    **New features**

    * **Burst rate limiting** -- introduced burst rate limit support for better throughput control
    * **Webhooks for waterfall and full enrich** -- webhook-based event delivery for waterfall and full enrich workflows
    * **Multi-dataset model relationships** -- models now support relationships across multiple datasets
    * **Package publishing through app** -- publish npm packages directly through the Cargo app

    **Integrations**

    * **Attio** -- added note creation and list notes actions
    * **Cognism** -- improved enrichment with chunked processing
    * **Snowflake** -- added batching support for actions
    * **BigQuery** -- added batch support

    **Improvements**

    * Increased LinkedIn rate limits
    * Added sync after model creation
    * Workflow termination on model deletion
    * Updated email waterfall and Salesforce dedup templates
  </Accordion>

  <Accordion title="Week of Feb 17–23" icon="calendar">
    **New features**

    * **Cargo SDK** -- introduced the official Cargo SDK for programmatic access
    * **Cargo CLI** -- introduced the Cargo command-line interface
    * **Waiting mode** -- implemented waiting mode for long-running workflow steps
    * **Message cancel** -- support for cancelling in-progress AI messages
    * **LinkedIn event attendees** -- new capability to extract LinkedIn event attendees

    **Integrations**

    * **Exa** -- new Exa search integration
    * **Gemini** -- added Gemini models with credit support
    * **Anthropic** -- added new Anthropic model variants

    **Improvements**

    * LinkedIn find profile URL capability
    * Human review now tracks user assignment and logs
    * File upload body limit increased to 2GB
    * Cancel downstream runs when parent is cancelled
    * Improved batch download performance
    * Renamed "agent deployment" to "trigger" across the UI
  </Accordion>

  <Accordion title="Week of Feb 10–16" icon="calendar">
    **New features**

    * **AI rate limiting** -- implemented rate limiting for AI language models and AI worker activities
    * **Node modal** -- new modal interface for node configuration
    * **Model DDL** -- introduced data definition language support for models
    * **SoR readonly queries** -- system of record now supports read-only query mode
    * **Enrollment filter** -- new filter type for enrollment-based targeting
    * **Trigger rename** -- renamed "tool launch" and "agent deployment" to "trigger" for consistency

    **Improvements**

    * More reliable model sync
    * LinkedIn find profile URL action
    * Improved segment filter validation
    * Credits support for company enrichment
    * Improved LinkedIn company enrichment coverage from domain
  </Accordion>

  <Accordion title="Week of Feb 3–9" icon="calendar">
    **New features**

    * **Lookup columns** -- introduced lookup columns for cross-model data references
    * **Recipes** -- re-introduced the recipes system for reusable workflow patterns
    * **Unification property modal** -- new modal for managing unification property mappings
    * **Confirmation modal for scheduled triggers** -- added a confirmation step when switching to scheduled trigger mode

    **Integrations**

    * **Anthropic** -- added Opus 4.6 model support
    * **OpenAI** -- added missing model variants
    * **Outreach** -- updated integration with opportunity prospect role and event types
    * **Apollo** -- updated search endpoint

    **Improvements**

    * Faster batch starts
    * Faster agent execution
    * Stripe subscription cancellation support
    * Upload limit increased to 500MB
  </Accordion>

  <Accordion title="Week of Jan 31 – Feb 2" icon="calendar">
    **New features**

    * **Integration language models** -- integrations can now expose their own language models for use in AI actions
    * **Bearer token auth** -- API now supports bearer token authentication

    **Integrations**

    * **Outreach** -- added event name selection for Outreach events

    **Improvements**

    * Improved file upload handling
    * Added description tooltips on file widget
  </Accordion>
</AccordionGroup>


# Manifest
Source: https://docs.getcargo.ai/cli/manifest

Scaffold a GTM repo readable by humans and coding agents alike

Manifest is the repo framework for GTM engineering: one conventional,
version-controlled repository holding everything your go-to-market runs on,
readable by humans and coding agents alike. `cargo-ai project init` scaffolds that
repo.

A Manifest repo has six layers:

| Layer   | Directory         | One sentence                                                                  |
| ------- | ----------------- | ----------------------------------------------------------------------------- |
| Context | `context/`        | What the company knows: the GTM brain every agent reads before acting         |
| Skills  | `.claude/skills/` | What agents know how to do in this specific repo                              |
| Infra   | `infra/`          | What runs in production, declared as a [project](/get-started/project-layout) |
| Scripts | `scripts/`        | What you run by hand, for surfaces the project cannot declare yet             |
| Evals   | `evals/`          | What keeps agents honest: prompt regression tests in CI                       |
| Outputs | `outputs/`        | What happened: the append-only archive agents read as memory                  |

The layer that executes (`infra/`) needs a Cargo workspace. The rest (context,
skills, evals, outputs, the context linter) work in any repo with no account at
all.

## `project init`

```bash theme={null}
# scaffold a fresh repo
cargo-ai project init acme-gtm

# or omit the directory and be asked — name, cookbook, install, and
# whether to hand the repo straight to your coding agent
cargo-ai project init
```

Options:

* `--name <name>` — repo name written into `package.json`
  (default: the directory name)
* `--cookbook <name>` — cookbook to install into the new repo, skipping the
  "Start from" question (`cargo-ai project cookbook list` names them)
* `--force` — scaffold into a non-empty directory (existing files are still
  kept, never overwritten)

Every repo is scaffolded from the same base, `getcargohq/cargo-manifest`. What
varies is what you layer on top of it — a cookbook, either with `--cookbook`
here or `cargo-ai project add` later.

Everything is one command group now: `cargo-ai manifest` was removed in
`@cargo-ai/cli` 1.0.70, because it scaffolded the same repo from the same base
as `cargo-ai project init` and the split only made you guess which one to run. The
standalone `cargo-cdk` bin takes the same subcommands, and `cargo-ai cdk` is
kept as an alias of `cargo-ai project`.

## Adding a cookbook

A cookbook is a worked example — resources, the procedure that operates
them, and the inputs it will ask you for. `add` installs one into a repo that
already exists, splitting it the way the repo is laid out: `infra/` to the
project, the rest to `.claude/skills/`.

```bash theme={null}
cargo-ai project cookbook list          # what is available
cargo-ai project cookbook view cookbook/tam-building
cargo-ai project add cookbook/tam-building
```

`add` never deploys. It reports every file it would overwrite and stops unless
you pass `--overwrite`, then prints what the cookbook still needs from you.
Omit the address to pick from the catalog.

## Growing the repo

Once the repo exists, add to it the way you add any other code:

* **Skills** — `npx skills add getcargohq/gtm-skills` installs one-job GTM
  skills your agent can run; `npx skills add getcargohq/cargo-skills` teaches it
  this CLI.
* **Resources** — declare models, plays, tools and agents in `infra/` as a
  [project](/get-started/project-layout), then `cargo-ai project plan` and
  `cargo-ai project deploy`.
* **A cookbook** — `cargo-ai project add cookbook/<name>` installs a worked example
  into the repo you already have.


# Cargo CLI Overview
Source: https://docs.getcargo.ai/cli/overview

The Cargo CLI gives you programmatic, terminal-level access to every part of the Cargo platform — models, connectors, workflows, agents, billing, and workspace administration.

The `@cargo-ai/cli` package mirrors the full Cargo platform surface as structured shell commands. Every response is JSON, every failure exits non-zero, and every asynchronous operation (runs, batches, agent messages) has a corresponding polling command. This makes the CLI a natural fit for automation pipelines, CI/CD workflows, and AI agents that need to operate Cargo without opening a browser.

This is the **imperative** way to work with Cargo — one-off, scripted commands. For managing a whole workspace as versioned code, use the declarative [project](/get-started/project-layout) (`cargo-ai project`, which ships in this same binary); for driving these commands with natural language, use [Skills](/skills/overview). See [Commands, project & skills](/get-started/commands-project-and-skills) for how the three fit together.

***

## Installation

Install from npm and authenticate once — the same login `project` and Skills reuse. The [Quickstart](/get-started/quickstart) has the full walkthrough (install, `login`, `whoami`, workspace targeting, and CI token setup):

```bash theme={null}
npm install -g @cargo-ai/cli && cargo-ai login --token <your-api-token>
```

Without a global install, prefix every command with `npx @cargo-ai/cli` instead of `cargo-ai`.

***

## Command domains

The CLI is organized into command groups — run `cargo-ai --help` for the full list, and `cargo-ai <group> --help` to drill in. The primary domains:

| Command group                  | Area        | What it does                                                                                                                                                    |
| ------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cargo-ai orchestration`       | Runtime     | Run tools on single records, trigger batch plays across segments, inspect runs/batches/spans/traces                                                             |
| `cargo-ai storage`             | Schema      | Inspect model DDL, create and update columns (custom, computed, metric, lookup), manage datasets, set model relationships                                       |
| `cargo-ai connection`          | Connectors  | Authenticate connector instances, list available integrations and their action slugs, discover native actions                                                   |
| `cargo-ai ai`                  | Agents      | Create and configure agents, manage releases (draft → deploy), chat with agents, connect MCP servers, inspect memories                                          |
| `cargo-ai segmentation`        | Segments    | List segments, fetch and download segment records with filters and sorts                                                                                        |
| `cargo-ai billing`             | Costs       | Track credit consumption by workflow, connector, or agent; check subscription status; view invoices                                                             |
| `cargo-ai workspaceManagement` | Admin       | Invite users, create and rotate API tokens, organize resources into folders, manage roles                                                                       |
| `cargo-ai mailboxManagement`   | Mailboxes   | Provision owned sending inboxes, start warm-up, inspect send allowance, list threads/events, manage suppressions                                                |
| `cargo-ai project`             | Declarative | Scaffold a [Manifest GTM repo](/cli/manifest), then plan, deploy, refresh, and destroy the [project](/get-started/project-layout) inside it (`cdk` is an alias) |

Other groups include `content`, `context`, `system-of-record`, `revenue-organization`, `hosting`, `mailboxManagement`, and `expression`.

<Note>
  **Cargo Skills** package these domains into prompt bundles so an AI agent can
  operate them from natural language — same commands, driven by an agent. See
  [Skills](/skills/overview).
</Note>

### How the domains relate

```mermaid theme={null}
graph TD
    workspace["<b>workspaceManagement</b><br/>Authentication, users, tokens, folders"]

    storage["<b>storage</b><br/>Models, columns, datasets"]
    connection["<b>connection</b><br/>Connectors, integration actions"]
    ai["<b>ai</b><br/>Agents, files, MCP servers"]

    orchestration["<b>orchestration</b><br/>Runs, batches, plays, tools"]

    billing["<b>billing</b><br/>Credit usage, costs, invoices"]
    mailboxes["<b>mailboxManagement</b><br/>Owned inboxes, threads, suppressions"]

    workspace --- storage
    workspace --- connection
    workspace --- ai
    workspace --- mailboxes

    storage -- "UUIDs flow down" --> orchestration
    connection --> orchestration
    ai --> orchestration
    mailboxes --> orchestration

    orchestration --> billing
```

***

## Key concepts

### Plays vs. Tools

|                      | Play                                       | Tool                           |
| -------------------- | ------------------------------------------ | ------------------------------ |
| **Trigger**          | Segment-driven (reactive)                  | On-demand (proactive)          |
| **Run command**      | `batch create`                             | `run create` or `batch create` |
| **Batch data kinds** | `segment`, `change`, `filter`, `recordIds` | `file`, `records`              |

<Warning>
  Using `run create` on a play's `workflowUuid` returns a `playNotCompatible`
  error. Plays must always use `batch create`.
</Warning>

### UUID discovery sequence

Most commands require UUIDs. Always discover them before acting:

```bash theme={null}
cargo-ai whoami                              # confirm workspace
cargo-ai orchestration play list             # → workflowUuid, modelUuid
cargo-ai orchestration tool list             # → workflowUuid
cargo-ai storage model list                  # → modelUuid
cargo-ai storage model get-ddl <model-uuid>  # → exact SQL table name
cargo-ai connection connector list           # → connectorUuid
cargo-ai ai agent list                       # → agentUuid
cargo-ai segmentation segment list           # → segmentUuid
cargo-ai mailboxManagement mailbox list      # → mailboxUuid
```

### UUID flow table

| UUID            | Produced by                        | Consumed by                                                             |
| --------------- | ---------------------------------- | ----------------------------------------------------------------------- |
| `workflowUuid`  | `play list` / `tool list`          | `run create`, `batch create`, metrics                                   |
| `modelUuid`     | `storage model list` / `play list` | `batch create --data '{"kind":"filter",...}'`, `segment fetch`, SoR DDL |
| `segmentUuid`   | `segmentation segment list`        | `batch create --data '{"kind":"segment",...}'`                          |
| `agentUuid`     | `ai agent list`                    | `ai chat create`, agent nodes in workflows                              |
| `connectorUuid` | `connection connector list`        | Connector nodes in workflows, billing filter                            |
| `actionSlug`    | `connection integration get`       | Connector nodes in workflows                                            |
| `batchUuid`     | `batch create`                     | `batch get`, `batch download`, run filter                               |
| `releaseUuid`   | `batch get`                        | `release get`, `run get-metrics --release-uuid`                         |
| `folderUuid`    | `workspaceManagement folder list`  | `play/tool/agent/mailbox update --folder-uuid`                          |
| `mailboxUuid`   | `mailboxManagement mailbox list`   | `sendEmail`, `message/thread/event list`                                |

### Async operations

All runs, batches, and agent messages are async. The REST create calls return
`202 Accepted` with a `Location` header pointing at the run or batch. Poll
that URL, or `run get` / `batch get` with the returned uuid.
Either use `--wait-until-finished` to block until completion, or poll manually:

| Operation     | Create           | Poll                          | Terminal statuses                          |
| ------------- | ---------------- | ----------------------------- | ------------------------------------------ |
| Run           | `run create`     | `run get <uuid>` every 2s     | `success`, `error`, `cancelled`, `skipped` |
| Batch         | `batch create`   | `batch get <uuid>` every 5s   | `success`, `error`, `cancelled`, `skipped` |
| Agent message | `message create` | `message get <uuid>` every 2s | done when `finishedAt` is set              |

### Filter syntax

Filters use a two-level structure with `conjonction` (not `conjunction` — this is intentional and silent if misspelled):

```json theme={null}
{
  "conjonction": "and",
  "groups": [
    {
      "conjonction": "and",
      "conditions": [
        {
          "kind": "string",
          "columnSlug": "country",
          "operator": "is",
          "values": ["US"]
        },
        {
          "kind": "number",
          "columnSlug": "employee_count",
          "operator": "greaterThan",
          "value": 100
        }
      ]
    }
  ]
}
```

**Operators by column type:**

| Type               | Available operators                                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `string`           | `is`, `isNot`, `contains`, `doesNotContain`, `startsWith`, `endsWith`, `isNull`, `isNotNull`, `isEmpty`, `isNotEmpty` |
| `number`           | `is`, `isNot`, `greaterThan`, `lowerThan`, `between`, `isNull`, `isNotNull`                                           |
| `date`             | `is`, `isNot`, `greaterThan`, `lowerThan`, `between`, `isNull`, `isNotNull`                                           |
| `boolean`          | `isTrue`, `isFalse`, `isNull`, `isNotNull`                                                                            |
| `object` / `array` | `isNull`, `isNotNull`, `matchConditions`                                                                              |

### Error handling

All failed commands exit non-zero and print JSON to stderr:

```json theme={null}
{ "error": "Human-readable description of what went wrong" }
```

API errors additionally include `status` and `body` fields with the HTTP response details.

To add automatic retries to connector nodes in a workflow, include a `retry` block in the node definition:

```json theme={null}
"retry": {
  "maximumAttempts": 3,
  "initialInterval": 1000,
  "backoffCoefficient": 2
}
```

***

## Common gotchas

| Gotcha                         | Rule                                                                                                                                    |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| Filter spelling                | Always write `conjonction`, never `conjunction`. Typo fails silently.                                                                   |
| `run create` vs `batch create` | `run create` is tool-only. Use `batch create` for plays.                                                                                |
| Triggering a play              | Use `{"kind":"filter","modelUuid":...}`. The `segmentUuid` from `play list` is the play's generated segment and fails with `noRecords`. |
| Segment fetch flag             | `segment fetch` and `segment download` require `--model-uuid`, not `--segment-uuid`.                                                    |
| DDL before SQL                 | Run `model get-ddl <uuid>` first — table names look like `datasets_default.models_companies`.                                           |
| Token security                 | API token values are shown once. Store immediately.                                                                                     |
| Invoice amounts                | `subscription get-invoices` returns amounts in cents. Divide by 100 for dollars.                                                        |
| Batch partial failure          | `status: success` on a batch can still contain individual run failures — always check `failedRunsCount`.                                |
| Rate limits                    | Only `kind: "connector"` nodes have rate limits. Native nodes do not. Ramp in stages: 1 → 50 → 500 → 1000+.                             |

***

## Next steps

<CardGroup>
  <Card title="Cargo Skills" icon="robot" href="/skills/overview">
    Install Cargo Skills and drive your entire workspace with natural language
    prompts.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Use the REST API directly for programmatic integrations beyond the CLI.
  </Card>

  <Card title="Tools" icon="wrench" href="/tools/overview">
    Define runnable automations in code with `defineTool` and `defineWorkflow`.
  </Card>

  <Card title="Agents" icon="sparkles" href="/agents/overview">
    Wire up an AI agent with `defineAgent` — tools, models, and sub-agents.
  </Card>
</CardGroup>


# Connectors
Source: https://docs.getcargo.ai/connectors/overview

Link Cargo to your CRM, warehouse, enrichment providers, and AI models with defineConnector — the foundation every model, tool, and agent builds on.

A **connector** is an authenticated link to an external system — a CRM, warehouse, enrichment API, or LLM provider. Creating one auto-provisions a **dataset** that data models source from, and exposes that integration's actions to your workflows and agents.

## Define a connector

```ts connectors/hubspot.ts theme={null}
import { defineConnector, secret } from "@cargo-ai/cdk";

export const hubspot = defineConnector("hubspot", {
  integration: "hubspot",
  config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
});
```

The `integration` slug selects which system to connect; `config` is a typed, per-integration shape (run [`cargo-ai project types`](/get-started/project-layout) to type it against your workspace). The connector handle carries deferred tokens — `hubspot` (the handle), `hubspot.datasetUuid` — that you pass into models and other resources.

## Secrets vs. config

Use `secret()` or `workspaceEnv()` for credentials, and `env()` for non-secret
config you want tracked:

```ts theme={null}
config: { apiKey: secret("PROVIDER_API_KEY") }        // this deploy's value, never hashed or stored
config: { apiKey: workspaceEnv("PROVIDER_API_KEY") }  // read from the workspace on every use
config: { region: env("PROVIDER_REGION") }            // tracked in the content hash
```

The two credential helpers differ in where the value lives. `secret()` reads
`process.env` at deploy time and sends the value, so rolling it means
re-deploying. `workspaceEnv()` sends only a pointer at the workspace's
[environment variables](/reference/secrets-and-environments#workspace-environment-variables),
which Cargo resolves on every run — so rotating it there takes effect
immediately, with no deploy. A connector config is one of the two places that
accepts a pointer.

<Warning>
  Always use `secret()` or `workspaceEnv()` — never `env()` — for credentials.
  Both are excluded from the content hash and from the deploy state. `env()`
  bakes the value into the hash, so rotating it reads as drift.
</Warning>

See [Secrets & environments](/reference/secrets-and-environments) for the full
rules and the `CARGO_*` variables the CLI reads.

## OAuth and existing connectors

Some integrations authenticate via OAuth in the browser rather than a static key. Adopt an already-connected instance by slug instead of re-creating it:

```ts connectors/openai.ts theme={null}
import { defineConnector } from "@cargo-ai/cdk";

export const openai = defineConnector("open_ai", {
  integration: "openAi",
  default: true,
});
```

<Note>
  `default: true` links an existing connector (e.g. one authorized through an
  OAuth flow in the workspace) rather than creating a new one. An adopted
  connector is **read-only**: deploys never push `name`, `config`, `rateLimit`
  or `cacheTtlMilliseconds` to it, so the credentials authorized outside the
  repo are never overwritten. A later `destroy` releases it instead of
  deleting it.

  Aside from unified models — which Cargo generates and a project can only bind
  to, never create — this is the only implicit link a project makes. Every other
  resource is created outright: if one with the same slug or name already
  exists, the deploy fails rather than adopting it. To bring an existing
  workspace resource under code, use `cargo-ai project pull`, or
  `cargo-ai project import <id> <uuid>` to bind one resource explicitly.
</Note>

## Using a connector

Once defined, a connector powers three things:

* **Data models** source from its dataset — see [Models](/models/overview) and [Extractors](/models/extractors).
* **Workflows** call its actions via `uses.<key>.<action>()` (declared in `uses`) — see [Workflows](/workflows/overview).
* **Agents** invoke its actions by referencing `connector.actions.<slug>` in their `uses` — see [Agents](/agents/overview).

Browse every available integration and its action slugs in the [Integrations](/integration/overview) section, or discover them live with `cargo-ai connection integration get <slug>` (or generate typed editor autocomplete with `cargo-ai project types`).

## From the CLI

```bash theme={null}
cargo-ai connection integration list          # available integrations
cargo-ai connection connector list            # your connected instances
cargo-ai connection connector create \
  --name "HubSpot - Prod" --slug hubspot_prod --integration-slug hubspot \
  --config '{ ... }'
```

## Using the UI

In the web app, go to **Settings → Integrations → Add connection**, pick the integration, and complete the auth flow (API key or OAuth). Connectors created in the UI are bound into code by slug, or with `default: true`. From the terminal, `cargo-ai project add connector/<integration>` authorizes one in the browser and writes the file for you.

## Slug rules

Connector slugs are `snake_case` (`my_source`) and validated at define time, so a bad slug fails in `plan` rather than mid-deploy.


# Context
Source: https://docs.getcargo.ai/context/overview

Sync your GTM knowledge base — markdown/MDX files — into the workspace context repository with defineContext.

**Context** is your workspace's GTM knowledge base: an ICP definition, personas, positioning, playbooks — the qualitative knowledge that grounds agents and workflows. `defineContext` syncs a local folder of markdown/MDX into the workspace's context repository as code.

## Define context

```ts context/context.ts theme={null}
import { defineContext } from "@cargo-ai/cdk";

export const context = defineContext({ path: "context" });
```

Everything under `path` is synced on deploy:

```text theme={null}
context/
├── context.ts
├── icp.md
└── personas/
    └── head-of-growth.md
```

Add a `.md`/`.mdx` file and it's picked up automatically; edit one and it re-syncs.

<Note>
  The sync is **additive** — files added in the UI are left in place. Your code
  is the source of truth for the files it manages, not for the whole repo.
</Note>

## Inline files

Alongside (or instead of) a local `path`, pass `files` to generate context entries in code — each key is a path in the repo, each value its contents. Inline files are merged over anything synced from `path`, so they can add to or override it:

```ts context/context.ts theme={null}
import { defineContext } from "@cargo-ai/cdk";

export const context = defineContext({
  path: "context", // sync a local folder of .md/.mdx
  files: { "generated/icp.md": buildIcp() }, // + inline additions/overrides
});
```

There is one context repo per workspace, so `defineContext` is a singleton.

## From the CLI

```bash theme={null}
cargo-ai context repository get
cargo-ai context graph get        # the knowledge graph derived from context
```


# Deploying
Source: https://docs.getcargo.ai/deploy/deploying

The project reconcile lifecycle — plan, deploy, prune, refresh, import and destroy — plus the flags that control confirmation, pruning and locking.

`cargo-ai project` reconciles your code against the live workspace. All commands accept
`--dir <path>` (defaults to the current directory) and resolve this project's
deploy state relative to it, through the `cargo.state.json` that names it.

Commands below are shown as `cargo-ai project <command>` (`cargo-ai cdk` is kept
as an alias). The engine ships inside the Cargo CLI, so there's no separate
install or login. If you'd rather not install
the CLI globally, the standalone `cargo-cdk` bin (`npx @cargo-ai/cdk <command>`)
exposes the identical subcommands; in a scaffolded project, `npm run plan` /
`deploy` / `types` are shortcuts for the common ones.

## Plan

```bash theme={null}
cargo-ai project plan
```

Compiles your resources and diffs them against this project's deploy state.
Output marks each resource `+ create`, `~ update`, `= noop`, or `- delete`
(state-tracked but no longer in code). It changes nothing, in the workspace or
on disk.

## Deploy

```bash theme={null}
cargo-ai project deploy            # create/update; prompts before applying
cargo-ai project deploy --yes      # skip the prompt (required in CI / non-TTY)
cargo-ai project deploy --dry-run  # show the plan, change nothing
```

`deploy` applies in dependency order and **persists state after each resource**,
so a crash mid-deploy leaves a recoverable state — just re-run.

<Steps>
  <Step title="Create">First deploy creates every resource and writes state.</Step>
  <Step title="No-op">Re-deploy with no code changes does nothing.</Step>
  <Step title="Update">Change one resource; only it updates.</Step>
</Steps>

### Prune

By default `deploy` never deletes. To remove resources you deleted from code:

```bash theme={null}
cargo-ai project deploy --prune
```

Without `--prune`, the plan still shows what *would* be pruned and reminds you.

### Refresh on deploy

```bash theme={null}
cargo-ai project deploy --refresh
```

Re-reads the live resources first and folds any out-of-band drift into the plan:
a resource edited in the UI re-applies (code wins). A resource **deleted** in the
UI is *not* silently recreated — the deploy stops and asks you to either re-run
with `--recreate-deleted` (to restore it) or remove it from your code (if the
deletion was intentional). See [State & drift](/deploy/state-and-drift).

## Import

Bind an existing live resource to a code resource — recover a lost state link, or
adopt pre-existing infra:

```bash theme={null}
cargo-ai project import agent:sdr 1a2b3c4d-...
```

Cargo reconstructs the resource's outputs and records it so the next deploy is
a no-op. Imported resources are treated as **adopted**: a later `destroy`
releases them (drops them from state) rather than deleting infra the project didn't
create.

### Referencing existing resources

You don't have to import (or define) a resource just to point at it. Every
builder that takes a handle also accepts a `xxRef(uuid)` — a typed reference to
a live resource the repo doesn't manage:

```ts theme={null}
import { defineModel, definePlay, connectorRef, playRef } from "@cargo-ai/cdk";

// A connector that was connected via OAuth in the UI
export const contacts = defineModel("contacts", {
  connector: connectorRef("9c26…"),
  extractSlug: "fetchRecords",
});

// Chain a code-defined play after one that only exists in the workspace
export const followUp = definePlay("follow-up", {
  model: contacts,
  schedule: { type: "dependency", play: playRef("1a2b…") },
});
```

Available refs: `connectorRef`, `modelRef`, `folderRef`,
`playRef`, `memberRef`, `segmentRef`, plus `toolRef` / `agentRef` for
workflow `uses`. The kind is branded, so a `modelRef` can't be passed where a
connector is expected. Referenced resources stay unmanaged: they're never
deployed, pruned, or destroyed by the project — the uuid is injected as-is.

Members are the exception worth knowing: `defineMember("alice@acme.com")` adopts
the live member with that email, so a territory doesn't have to hardcode uuids
that only exist in one workspace.

## Rollback

```bash theme={null}
cargo-ai project rollback
```

Restores this project's deploy state from the snapshot taken before the last
deploy/destroy/import. It restores the **state only** — live resources are
untouched — so follow it with `cargo-ai project deploy --refresh` to reconcile the
workspace back to it. Accepts `--yes` to skip the prompt and `--force` to steal
a stale lock.

## Destroy

```bash theme={null}
cargo-ai project destroy --all                   # tear down everything in state
cargo-ai project destroy --target play:welcome   # just one resource
```

Blanket teardown is opt-in: `destroy` refuses unless you pass `--all` or
`--target <id>` (so `--yes` alone can't wipe a workspace). It deletes by uuid in
dependency-safe order (dependents first) and **releases** adopted resources
instead of deleting them. A `--target` that still has dependents — or that
isn't in state — is rejected rather than silently skipped.

<Warning>
  `destroy` and `deploy --prune` delete real Cargo resources. With `--yes` they
  skip the prompt — double-check `--dir` and that `cargo.state.json` points at
  the state for the workspace you intend.
</Warning>

## Locking & `--force`

A deploy/destroy/import holds a lock on the state for the whole read→plan→apply
sequence so two concurrent runs can't corrupt it — across machines, not just
across processes on one. A lock left by a run that died expires after an hour;
to override one you believe is stale:

```bash theme={null}
cargo-ai project deploy --force
```

## Programmatic use

`plan`/`apply` are exported, so CI or the backend can reconcile the same way:

```ts theme={null}
import { loadResources, apply, liveExecutors, liveReaders, resolveStateBackend, emptyState } from "@cargo-ai/cdk";

// Reads cargo.state.json and hands back the state it names — the one in your
// workspace, or the file itself for a project that still holds its own map.
const { backend } = await resolveStateBackend({ root, mode: "write", getApi: () => api });

const nodes = await loadResources(root); // import the repo's resource files
const prior = await backend.read();
const state = prior !== undefined ? prior : emptyState(workspaceUuid);
await apply({ nodes, state }, liveExecutors(api), (next) => backend.write(next), liveReaders(api));
```

<Warning>
  Go through the backend rather than `readState`/`writeState`. Those read and
  write the committed file directly, so against a project whose state lives in
  the workspace they would see nothing deployed, create a second copy of every
  resource, and overwrite the pointer with the map they built. `writeState`
  refuses that, but the backend is the path that works.
</Warning>


# Monitoring
Source: https://docs.getcargo.ai/deploy/monitoring

Inspect runs, batches, spans, and traces from the CLI — and set up alerts — to see how your tools, plays, and agents perform.

Every execution in Cargo — a tool run, a play batch, an agent message — is observable from the terminal. Runs, batches, spans, and traces all have list, get, and metrics commands.

## Runs and batches

```bash theme={null}
cargo-ai orchestration run list --workflow-uuid <uuid>
cargo-ai orchestration run get <run-uuid>
cargo-ai orchestration run get-metrics --workflow-uuid <uuid>

cargo-ai orchestration batch list
cargo-ai orchestration batch get <batch-uuid>
cargo-ai orchestration batch download --uuid <batch-uuid>   # results as a file
```

<Warning>
  A batch with `status: success` can still contain individual run failures —
  always check `failedRunsCount`.
</Warning>

## Spans and traces

Drill into a single execution's node-by-node breakdown:

```bash theme={null}
cargo-ai orchestration trace list --started-after 2025-01-01 --workflow-uuid <uuid>
cargo-ai orchestration trace get <trace-uuid>
cargo-ai orchestration span list --execution-started-after 2025-01-01 --run-uuid <run-uuid>
```

<Note>
  `trace list` requires `--started-after`, and `span list` requires
  `--execution-started-after` — both accept an ISO date. The uuid flags narrow
  the results but are optional.
</Note>

## Metrics

`get-metrics` returns per-node execution status counts and credits used, filterable by release, batch, or date range — so you can spot regressions between deploys.

```bash theme={null}
cargo-ai orchestration run get-metrics --workflow-uuid <uuid> \
  --created-after 2025-01-01 --created-before 2025-01-31
```

## Alerts

An [alert](/alerts/overview) makes this telemetry watch itself. It runs on a cron, computes a metric over the spans since its last tick — error rate, a duration percentile, credits, or span count — and fires actions as runs when the value breaches a threshold. Define one with `defineAlert`, or drive it from the CLI:

```bash theme={null}
cargo-ai observability alert list
cargo-ai observability alert preview \
  --scope '{"kind":"spans","workflowUuid":"<uuid>"}' \
  --threshold '{"metric":"errorRate","operator":"gte","value":10}'
```

A play can also declare its own batch-health threshold and alert actions — see [Plays](/plays/overview#fallbacks-and-health).

## Using the UI

Each tool and play also has **Records** and **Metrics** views in the web app — filter by status, version, batch, or date; inspect any execution node-by-node; and retry failed runs individually or in bulk (from scratch or from the failed node).


# State & Drift
Source: https://docs.getcargo.ai/deploy/state-and-drift

How your project's deploy state links code to deployed Cargo resources, the cargo.state.json pointer you commit, the deploy lock, and detecting changes made outside the project with project refresh.

## Deploy state

Every deploy records a map from each code resource (`kind:slug`) to the real
uuid Cargo assigned it, plus its outputs and a content hash:

```json theme={null}
{
  "version": 1,
  "workspaceUuid": "fbe3...",
  "resources": {
    "connector:hubspot": { "hash": "sha256:…", "uuid": "9c26…", "outputs": { "uuid": "9c26…", "datasetUuid": "f12c…" } }
  }
}
```

That map is the authoritative link from code to deployed infra. Connectors and
models are slug-addressable and self-heal, but **plays, agents, tools, files and
MCP servers have no slug** — their stored uuid is the only way to re-find them.

**It lives in your workspace, not in the repo.** The repo commits a pointer to
it:

```json theme={null}
{
  "stateUuid": "8f2c…"
}
```

`cargo-ai project init` creates the state and writes that `cargo.state.json` as part
of the scaffold, so the pointer is in the first commit rather than appearing in
whichever teammate deploys first. It records only uuids, hashes and outputs —
**never secret values**.

<Warning>
  **Commit `cargo.state.json`.** Without the uuid, a fresh checkout has no way to
  find the state it belongs to. Deleting it does not silently make a new one — a
  deploy stops and tells you to run `cargo-ai project state list` and
  `cargo-ai project state bind <uuid>`, because creating a replacement would orphan
  everything the old state tracks.
</Warning>

### One state per repo, many per workspace

A state belongs to a git repo, not to a workspace. Each `project init` creates its
own and commits its own uuid, so a workspace holding five GTM repos holds five
states and they never share a map.

| Situation                               | What to do                                                                                                  |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| A second repo in the same workspace     | Nothing — its own `project init` creates its own state                                                      |
| A second project inside one repo        | `cargo-ai project state create` in that directory, giving it a second pointer                               |
| Staging and production                  | Two workspaces, so two states. Init or log in against the one you are targeting                             |
| A fork that should deploy independently | `cargo-ai project state create --force` — it copied the pointer, so until then it deploys over the original |
| `project init` ran signed out           | The pointer landed without a uuid. `cargo-ai login`, then `cargo-ai project state create`                   |
| `cargo.state.json` was lost             | `cargo-ai project state list`, then `cargo-ai project state bind <uuid>`                                    |

### Managing it

```bash theme={null}
cargo-ai project state list          # every state in the workspace, and which one you are on
cargo-ai project state create        # create one for this project and write the pointer
cargo-ai project state bind <uuid>   # point this project at an existing one
```

### Projects created before states moved to the workspace

Their `cargo.state.json` holds the resource map itself, and it keeps working:
`plan`, `deploy` and everything else read and write that file exactly as they
did. The file *is* the state, so losing it has no recovery path but git.

Moving one into the workspace is a single command, run once by one person:

```bash theme={null}
cargo-ai project state create   # map moves onto a new state, file becomes a pointer
git commit cargo.state.json
```

<Note>
  Nothing migrates a project on its own. The pointer has to reach your teammates
  through git — if a deploy moved the map for whoever ran it first, everyone
  still on the old file would carry on deploying from a state that had already
  moved.
</Note>

There is no flag to choose between the two: the shape of the file decides.
Resources present means the file holds the state, a `stateUuid` means the
workspace does. Anything that let you contradict it would only ever deploy a
second copy of everything the pointer already tracks.

### Lock and sibling files

A deploy takes a lock on the state for its duration, so two runs cannot
interleave writes. A lock is released when the run ends, and one left by a run
that died expires after an hour; `--force` steals one you believe is stale.

Cargo also writes sibling files next to `cargo.state.json` — a
`cargo.state.bak.json` (local rollback snapshot), a `cargo.state.audit.jsonl`
(run log), a `cargo.state.lock` (local backend only), and a
`cargo.state.cache.json` (the last blob read from the workspace, so `project info`
can report what is deployed without a round trip). Only `cargo.state.json` is
committed; **git-ignore the rest**:

```gitignore theme={null}
.cargo-ai/            # generated by `project types`
cargo.state.lock
cargo.state.bak.json
cargo.state.cache.json
cargo.state.audit.jsonl
```

## Drift

Cargo compares your code against state. It can also compare against the live
workspace to catch changes made **outside** the project (e.g. someone edits an agent
in the Cargo UI, or deletes a folder).

### Detect (read-only)

```bash theme={null}
cargo-ai project refresh
```

Re-reads every state-tracked resource and reports each as `unchanged`,
`modified externally`, or `deleted externally`. It changes nothing.

### Correct

```bash theme={null}
cargo-ai project deploy --refresh
```

Folds the drift into the plan before applying:

* **Modified externally** → re-applies your code over it (**code wins**).
* **Deleted externally** → the deploy **stops** and asks you to re-run with
  `--recreate-deleted` before it will recreate anything — a deliberate gate so a
  resource someone removed on purpose doesn't silently come back.

<Note>
  Drift is measured against the state captured at the last deploy, not guessed
  from code — so it reflects real changes to the live resource. A transient read
  error is reported as `unknown`, never as a deletion, so a network blip can't
  trigger a mass re-create.
</Note>

## Code and UI round-trips

Resources deployed from code remain fully editable in the Cargo UI — but the
project never reads those edits back into your files. What happens to UI work on
the next deploy follows directly from the hash model:

* **A plain `project deploy` compares code against state, not against the live
  workspace.** If you haven't changed a resource in code, it plans as
  `=` unchanged and is skipped — UI edits to it survive every deploy.
* **The moment you change that resource in code**, the next deploy pushes the
  full code spec and overwrites the resource — including anything changed in
  the UI since.
* **`project deploy --refresh` re-applies code over every externally-modified
  resource**, whether or not its code changed. Reach for it when you want to
  reset to what the repo says; avoid it while UI work is in flight.

The practical rule: **pick one owner per resource.** Starting a workflow in
code and finishing canvas-only parts in the UI works — but from then on treat
the UI as that resource's source of truth: leave its code definition alone, or
port the canvas changes back into code before touching it again. Run
`cargo-ai project refresh` before deploying to see exactly which resources have
diverged.

## Secrets and drift

Because `secret()` values are excluded from the content hash, **rotating a secret
does not show as drift** and a plain `deploy` won't push the new value (nothing
changed). To roll a rotated secret, re-apply the resource (make any other change,
or use `--refresh`). Use `env()` instead if you *want* a config value tracked in
the hash. See [Secrets & environments](/reference/secrets-and-environments) for
the full `secret()` vs `env()` rules and how to deploy the same code to a second
workspace.


# Files
Source: https://docs.getcargo.ai/files/overview

Upload unstructured content — documents, PDFs, playbooks — as searchable resources with defineFile.

**Files** are unstructured resources — documents, PDFs, transcripts, playbooks. When attached to an agent or tool, their content is chunked and embedded so it can be retrieved by meaning (semantic search), not just keywords. You upload one from a local path with `defineFile`.

## Define a file

```ts files/playbook.ts theme={null}
import { defineFile } from "@cargo-ai/cdk";

export const playbook = defineFile("playbook", {
  path: new URL("./playbook.md", import.meta.url).pathname,
});
```

The content is uploaded on deploy; the file handle can then be referenced as an agent resource.

## Supported types

| Type          | Extensions                 |
| ------------- | -------------------------- |
| Documents     | `.pdf`, `.docx`, `.doc`    |
| Text          | `.txt`, `.md`, `.markdown` |
| Presentations | `.pptx`, `.ppt`            |
| Spreadsheets  | `.xlsx`, `.xls`, `.csv`    |

## Using files in agents

Attach files (or folders of files) as agent [resources](/agents/resources-and-context). The agent searches them with vector similarity — a query for "pricing concerns" surfaces content about "cost objections" even without the exact words. Add a description to steer how the agent prioritizes the content.

## From the CLI

```bash theme={null}
cargo-ai content file upload --file ./playbook.pdf
cargo-ai content file list
cargo-ai content library list      # group files into retrieval libraries
```

<Note>
  For structured, queryable data (CRM objects, tables) use
  [models](/models/overview) instead — files are for unstructured knowledge.
</Note>


# Folders
Source: https://docs.getcargo.ai/folders/overview

Organize resources of a given kind into folders with defineFolder.

**Folders** organize resources in the workspace UI. They are **per-kind** — a `model` folder and an `agent` folder are separate namespaces — so you place each resource in a folder of its own kind. You define one with `defineFolder`. `kind` is `model`, `agent`, `play`, `tool`, `file`, `mcpServer`, `app`, `worker`, `alert`, or `mailbox`.

## Define folders

```ts folders/crm.ts theme={null}
import { defineFolder } from "@cargo-ai/cdk";

export const modelsFolder = defineFolder("crm-models", { kind: "model", name: "CRM" });
export const agentsFolder = defineFolder("crm-agents", { kind: "agent", name: "CRM" });
```

Pass a folder handle into the resource it organizes:

```ts theme={null}
export const contacts = defineModel("contacts", {
  connector: hubspot,
  extractSlug: "fetchRecords",
  folder: modelsFolder,
});

export const jane = defineMailbox("jane", {
  domain: outreach,
  type: "google",
  firstName: "Jane",
  lastName: "Doe",
  folder: mailboxFolder,
});
```

## From the CLI

```bash theme={null}
cargo-ai workspaceManagement folder list
cargo-ai workspaceManagement folder create --name "Enrichment" --emoji-slug sparkles --kind tool
```


# Commands, project & skills
Source: https://docs.getcargo.ai/get-started/commands-project-and-skills

Three ways to operate Cargo through one binary and one login: imperative commands for one-off work, a declarative project for a whole workspace in git, and agent Skills so Claude Code, Codex, or Cursor can do it from a plain-English request. Signing up is free — 100 credits, no card.

There are three ways to drive Cargo, and they're not separate tools — they're three modes of the **same** command-line tool.

## One binary, one login

Everything runs through a single binary, `cargo-ai`, installed and authenticated once (see the [Quickstart](/get-started/quickstart)) — every mode below reuses that same session:

* **Imperative commands** — `cargo-ai orchestration run create`, `cargo-ai storage model list`, … operate the platform directly.
* **The project** ships *inside* the same binary as `cargo-ai project` (`plan`, `deploy`, `refresh`, `destroy`). There is no separate install or login.
* **Skills** are prompt packages that teach an AI agent to call those same commands for you.

So "CLI vs project" is not a real choice of tools — `project` is a command group of the CLI. The real choice is *which mode fits the task*.

<Note>
  `cargo-ai project` used to be called `cargo-ai cdk`, and `cdk` still works as
  an alias — nothing you have written down needs changing. The TypeScript
  library you import from is still [`@cargo-ai/cdk`](https://www.npmjs.com/package/@cargo-ai/cdk).
</Note>

## The three modes

```mermaid theme={null}
flowchart TD
  bin["cargo-ai — one binary, one login"]
  bin --> imp["<b>Imperative</b><br/>cargo-ai orchestration / storage / connection / ai …"]
  bin --> dec["<b>Declarative</b><br/>cargo-ai project plan / deploy (define* files + state)"]
  bin --> agent["<b>Agent-driven</b><br/>Skills → natural language → CLI commands"]
```

| Mode                      | You write…                                                          | Reach for it when…                                                                                                                                 |
| ------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Commands** (imperative) | one-off commands in a terminal or script                            | you want to run, inspect, or script a single operation — enrich a record, trigger a batch, query data, chat with an agent — without managing state |
| **Project** (declarative) | `define*` TypeScript files, deployed with `cargo-ai project deploy` | you want your whole workspace as versioned, diffable code with `plan`/`deploy` and drift detection                                                 |
| **Skills** (agent-driven) | plain-English prompts to an AI agent                                | you want an agent to figure out the exact commands and UUIDs from a description of the goal                                                        |

## How they fit together

* **Declarative is the default for anything you keep.** Connectors, models, tools, agents, and plays belong in a [project](/get-started/project-layout) so they're reproducible. Start with the [Quickstart](/get-started/quickstart).
* **Imperative is for operating what you've deployed.** Once a tool or play exists, you run and monitor it with [CLI commands](/cli/overview) — one-offs, CI jobs, data pulls.
* **Skills sit on top of the CLI.** They're the imperative surface, driven by an agent instead of your fingers. See [Skills](/skills/overview).

<Note>
  A quick rule of thumb: if you'd commit it to git, define it in the
  **project**. If you'd type it once, use a **command**. If you'd rather
  describe it than remember the flags, use **Skills**.
</Note>

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/get-started/quickstart">
    Deploy your first workspace from a project.
  </Card>

  <Card title="Project layout" icon="folder-tree" href="/get-started/project-layout">
    How a folder of define\* files becomes a workspace.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/overview">
    The imperative command surface — runs, batches, queries, and more.
  </Card>

  <Card title="Skills" icon="robot" href="/skills/overview">
    Drive the CLI with natural language through an AI agent.
  </Card>
</CardGroup>


# Project layout
Source: https://docs.getcargo.ai/get-started/project-layout

How a Cargo workspace is organized as files, how the loader turns them into resources, and how state keeps code and live infra in sync.

A Cargo workspace is a directory of TypeScript files. The CLI imports every `.ts` file under the project root, and each `define*` call registers a resource as a side effect. There is **no manifest** — the files *are* the interface.

## A worked layout

A project that exercises every resource type and wires them together looks like
this. `cargo-ai project init <dir>` scaffolds the repo around it — the tree below is
what grows inside `infra/` as you declare things. For a guided walkthrough that
builds and deploys the whole tree, see the [End-to-end recipe](/get-started/recipe):

```text theme={null}
my-workspace/
├── package.json          # scripts: "plan": "cargo-ai project plan", "deploy": "cargo-ai project deploy"
├── tsconfig.json         # includes .cargo-ai/**/*.d.ts for typed config
├── cargo.state.json      # written by `project init` — commit it
├── connectors/
│   ├── hubspot.ts        # defineConnector + secret()
│   └── openai.ts         # defineConnector({ adopt: true })
├── folders/crm.ts        # defineFolder (per-kind: model, agent, …)
├── models/contacts.ts    # defineModel — dataset handle + extractSlug + schedule
├── tools/enrich.ts       # defineWorkflow + defineTool
├── agents/
│   ├── enricher.ts       # defineAgent (sub-agent)
│   └── sdr.ts            # defineAgent (models, tools, subAgents, triggers, evaluator)
├── plays/onboarding.ts   # definePlay + per-row defineWorkflow
├── mcp/crm.ts            # defineMcpServer
├── context/              # defineContext + markdown/MDX
├── files/                # defineFile + local content
├── workers/webhook/      # defineWorker → a built bundle
└── apps/dashboard/       # defineApp → a Vite bundle
```

## How the loader works

* **Every `.ts` file is imported.** Importing registers whatever `define*` calls it contains. To add a resource, add a file.
* **Handles create dependencies.** `define*` returns a handle whose outputs (`uuid`, `datasetUuid`, …) are deferred tokens. Passing a handle into another builder (e.g. `connector: hubspot`, or an agent's `uses: [enrich]`) both orders the deploy and injects the real uuid. The dependency graph is your variable graph.
* **Bundle directories are skipped.** A subdirectory with its own `package.json` (a worker or app bundle) is treated as content to upload, not a resource file to import.

## `cargo.state.json`

Your project's **deploy state** is the authoritative map from each code resource
(`kind:slug`) to the real uuid Cargo assigned it, plus outputs and a content
hash. It lives in your workspace; `cargo.state.json` is the pointer to it that
`project init` writes and every later run follows.

<Warning>
  **Commit `cargo.state.json`.** Connectors and models are slug-addressable and
  self-heal, but plays, agents, tools, files, and MCP servers have no slug —
  their stored uuid is the only way to re-find them. Without the pointer a fresh
  checkout cannot find the state it belongs to — recover it with
  `cargo-ai project state list` and `cargo-ai project state bind <uuid>`, or recover one
  lost resource with `cargo-ai project import <id> <uuid>`.
</Warning>

The lock/backup/cache/audit siblings are ephemeral — git-ignore them:

```gitignore theme={null}
.cargo-ai/
cargo.state.lock
cargo.state.bak.json
cargo.state.cache.json
cargo.state.audit.jsonl
```

Each repo gets its own state, so a workspace can hold as many as you have
projects. See [State & drift](/deploy/state-and-drift) for the full model.

## Which `init` do I want?

There are several scaffold/init commands — don't confuse them:

| Command                                | What it does                                                      |
| -------------------------------------- | ----------------------------------------------------------------- |
| `cargo-ai project init <dir>`          | Scaffold a **GTM repo** with the project in `infra/` (this page). |
| `cargo-ai project add cookbook/<name>` | Install a **worked cookbook** into a repo you already have.       |
| `cargo-ai hosting app init <dir>`      | Scaffold a hosted **Vite app** bundle.                            |
| `cargo-ai hosting worker init <dir>`   | Scaffold a hosted **edge worker** bundle.                         |

## Next steps

<CardGroup>
  <Card title="Connectors" icon="plug" href="/connectors/overview">
    Start wiring in your data sources.
  </Card>

  <Card title="Deploying" icon="rocket" href="/deploy/deploying">
    The full reconcile lifecycle and its flags.
  </Card>

  <Card title="State & drift" icon="database" href="/deploy/state-and-drift">
    How state tracks live resources and detects out-of-band changes.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.getcargo.ai/get-started/quickstart

Install the Cargo CLI, authenticate, scaffold a workspace, define a tool, and deploy it — end to end.

This walks you from zero to a deployed, runnable tool. It takes a few minutes and one login shared by the CLI, your project, and Cargo Skills.

## 1. Install

```bash theme={null}
npm install -g @cargo-ai/cli
```

Without a global install, prefix every command with `npx @cargo-ai/cli` instead of `cargo-ai`.

## 2. Authenticate

You do not need an account first. `--email` mails a one-time code and creates the account and a workspace on first use, so there is no separate sign-up step and no browser at any point:

```bash theme={null}
cargo-ai login --email you@company.com          # sends the code, then exits
cargo-ai login --email you@company.com --code 123456
```

Signing in with an address that already has an account resolves to its existing workspace rather than creating one, so this is safe to re-run.

<Tip>
  In an **agent or sandbox shell** with no terminal to prompt at, the first call
  sends the code and exits — re-run it with `--code`. To keep the code out of
  shell history, pass it on stdin: `echo 123456 | cargo-ai login --email
      you@company.com --code -`
</Tip>

The alternatives: `cargo-ai login --oauth` signs in through the browser using the
OAuth device flow, and `cargo-ai login --token <your-api-token>` uses a token you
created under **Settings > API**.

To target a specific workspace, pass `--workspace-name "Acme GTM"` or
`--workspace-uuid <uuid>` at login, or set the `CARGO_WORKSPACE_UUID` environment
variable — otherwise commands run against your default workspace.

<Warning>
  API token values are shown only once at creation time. Store them immediately
  in a secrets manager (GitHub Secrets, AWS Secrets Manager, 1Password, …).
</Warning>

Verify:

```bash theme={null}
cargo-ai whoami
# → {"user":{"email":"you@example.com"},"workspace":{"name":"My Workspace"}}
```

<Tip>
  In CI, or in an AI coding agent that already has a token, you can skip
  `cargo-ai login` entirely and set the token via the `CARGO_API_TOKEN`
  environment variable — it takes precedence over saved credentials:
  `export CARGO_API_TOKEN=<your-api-token>`.
</Tip>

## 3. Scaffold a workspace

```bash theme={null}
cargo-ai project init my-workspace
cd my-workspace
npm install
```

`project init` scaffolds a [Manifest GTM repo](/cli/manifest) from `getcargohq/cargo-manifest`, with the project in `infra/`. Run it without a directory to be asked instead. `init` installs the dependencies for you; the `npm install` above is only there if you declined or it failed. There is one install, at the repo root — `infra/` is a source directory with no manifest of its own.

Every `project` command below finds `infra/` from the repo root, so you can stay where you are. Declaring a resource is writing a file under `infra/` and importing it — here is one AI-powered tool that needs **no third-party API keys**, so you can deploy and run it with nothing but your Cargo login:

```ts infra/tools/enrich.ts theme={null}
import { defineTool, defineWorkflow } from "@cargo-ai/cdk";
import { z } from "zod";

const enrichFlow = defineWorkflow(
  "enrich-contact",
  {
    input: z.object({ email: z.string() }),
    output: z.object({ company: z.string() }),
  },
  ({ input, ai }) => {
    const company = ai(
      `What company owns the email domain of ${input.email}? Reply with just the company name.`,
    );
    return { company };
  },
);

export const enrich = defineTool("enrich", {
  workflow: enrichFlow,
  description: "Enrich a contact with firmographic data.",
  emojiSlug: "mag",
});
```

## 4. Generate types (optional but recommended)

```bash theme={null}
cargo-ai project types
```

This reads your workspace and writes typed connector/model config and the `uses.<key>.<action>` action registry into `.cargo-ai/`, so your editor autocompletes real action slugs.

## 5. Plan and deploy

```bash theme={null}
cargo-ai project plan               # diff against this project's deploy state
cargo-ai project deploy             # create everything; record it in the state
```

`deploy` applies in dependency order and records each resource's real uuid in this project's deploy state, which lives in your workspace. **Commit `cargo.state.json`** — it is the pointer that finds it. The next deploy only changes what changed.

## 6. Run your tool

```bash theme={null}
cargo-ai orchestration tool list                         # → workflowUuid
cargo-ai orchestration run create \
  --workflow-uuid <uuid> \
  --data '{"email":"ada@acme.com"}' \
  --wait-until-finished
```

The run's output includes the company name — your first deployed tool, end to end. It's also live in your workspace at [app.getcargo.io](https://app.getcargo.io), where you can open it in the visual editor and inspect its runs.

## 7. Wire a real data source (optional)

Connectors bring your CRM, warehouse, and enrichment providers into the same project — for example HubSpot, using a [private-app token](/integration/hubspot) kept out of git with `secret()`:

```ts infra/connectors/hubspot.ts theme={null}
export const hubspot = defineConnector("hubspot", {
  integration: "hubspot",
  config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
});

export const contacts = defineModel("contacts", {
  connector: hubspot,
  extractSlug: "fetchRecords",
});
```

```bash theme={null}
export HUBSPOT_API_KEY=...      # secret() reads this at deploy time
cargo-ai project deploy             # only the new resources are created
```

<Tip>
  `secret()` reads from `process.env` at deploy time. To keep the key in the
  workspace instead of your shell, use `workspaceEnv("HUBSPOT_API_KEY")`. See
  [Secrets & environments](/reference/secrets-and-environments) for how the
  three helpers differ, the `CARGO_*` variables, and deploying the same code to
  a second workspace.
</Tip>

## Next steps

<CardGroup>
  <Card title="Project layout" icon="folder-tree" href="/get-started/project-layout">
    How the loader turns a folder of files into a workspace.
  </Card>

  <Card title="Commands, project & skills" icon="signs-post" href="/get-started/commands-project-and-skills">
    The three ways to drive Cargo — and when to reach for each.
  </Card>

  <Card title="Connectors" icon="plug" href="/connectors/overview">
    Link your CRM, warehouse, enrichment, and AI providers.
  </Card>

  <Card title="Deploying" icon="rocket" href="/deploy/deploying">
    plan, deploy, prune, refresh, import, and destroy.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/overview">
    Run tools, trigger plays, and query your data from the terminal.
  </Card>
</CardGroup>


# End-to-end recipe
Source: https://docs.getcargo.ai/get-started/recipe

Wire a connector, model, tool, agent, and play together in one workspace, deploy it with cargo-ai project, and run it — the full loop end to end.

This recipe builds a small but complete workspace: a **connector** feeds a
**model**, a **tool** enriches a record, an **agent** reasons over the data, and
a **play** runs a workflow as rows change. Then you deploy it all with one
command and run it. Every snippet uses the same `define*` builders documented in
[Resources](/connectors/overview).

It builds the tree described in [Project layout](/get-started/project-layout),
inside the `infra/` of a repo scaffolded by `cargo-ai project init <dir>`.

## 1. Connect

Define the source system and the LLM provider. Use `secret()` for API keys, or
`cargo-ai project add connector/<slug>` for one authorized via OAuth in the app.

```ts connectors/hubspot.ts theme={null}
import { defineConnector, secret } from "@cargo-ai/cdk";

export const hubspot = defineConnector("hubspot", {
  integration: "hubspot",
  config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
});
```

```ts connectors/openai.ts theme={null}
import { defineConnector } from "@cargo-ai/cdk";

export const openai = defineConnector("open_ai", {
  integration: "openAi",
  default: true,
});
```

## 2. Model

Source a model from the connector's dataset with an `extractSlug`. Discover the
valid slugs and config with `cargo-ai project types` or
`cargo-ai connection integration get <slug>`.

```ts models/contacts.ts theme={null}
import { defineModel } from "@cargo-ai/cdk";
import { hubspot } from "../connectors/hubspot";

export const contacts = defineModel("contacts", {
  connector: hubspot,
  extractSlug: "fetchRecords",
  config: { objectType: "contacts", columnSelectionMode: "all" },
  schedule: { type: "cron", cron: "0 * * * *" },
});
```

## 3. Tool

A tool is a [workflow](/workflows/overview) you can run on demand. Build the
workflow with `defineWorkflow`, then wrap it in `defineTool`.

```ts tools/enrich.ts theme={null}
import { defineTool, defineWorkflow } from "@cargo-ai/cdk";
import { z } from "zod";

const enrichFlow = defineWorkflow(
  "enrich-contact",
  {
    input: z.object({ email: z.string() }),
    output: z.object({ company: z.string() }),
  },
  ({ input, ai }) => ({
    company: ai(`Which company owns the domain of ${input.email}?`),
  }),
);

export const enrich = defineTool("enrich", { workflow: enrichFlow });
```

## 4. Agent

An agent reasons over the models, tools, and connector actions you hand it. Pass
handles — Cargo deploys dependencies first and injects their uuids.

```ts agents/sdr.ts theme={null}
import { defineAgent } from "@cargo-ai/cdk";
import { openai } from "../connectors/openai";
import { contacts } from "../models/contacts";
import { enrich } from "../tools/enrich";

export const sdr = defineAgent("sdr", {
  connector: openai,
  languageModel: "gpt-4o",
  systemPrompt: "Qualify inbound contacts and enrich missing company info.",
  capabilities: ["webSearch", "memory"],
  uses: [{ ref: contacts, readOnly: true }, enrich],
});
```

## 5. Play

A play runs a per-row workflow as the model's rows change.

```ts plays/onboarding.ts theme={null}
import { definePlay, defineWorkflow } from "@cargo-ai/cdk";
import { z } from "zod";
import { contacts } from "../models/contacts";
import { enrich } from "../tools/enrich";

const onboardRow = defineWorkflow(
  "onboard-contact",
  { input: z.object({ email: z.string() }), output: z.object({ done: z.boolean() }), uses: { enrich } },
  ({ input, uses }) => {
    uses.enrich({ email: input.email });
    return { done: true };
  },
);

export const onboarding = definePlay("onboarding", {
  model: contacts,
  workflow: onboardRow,
  changeKinds: ["added"],
  schedule: { type: "realtime" },
});
```

## 6. Deploy

```bash theme={null}
export HUBSPOT_API_KEY=...   # secret() reads this at deploy time
cargo-ai project plan            # diff against this project's deploy state
cargo-ai project deploy          # create everything; record it in the state
```

`deploy` applies in dependency order (connector → model → tool → agent → play)
and records each resource's uuid in this project's deploy state. **Commit
`cargo.state.json`** — it is the pointer that finds it. See
[Secrets & environments](/reference/secrets-and-environments) for `secret()`,
`workspaceEnv()` and the `CARGO_*` variables.

## 7. Run

Run the tool on a single record, then chat with the agent:

```bash theme={null}
cargo-ai orchestration tool list                         # → workflowUuid
cargo-ai orchestration run create \
  --workflow-uuid <uuid> \
  --data '{"email":"ada@acme.com"}' \
  --wait-until-finished

cargo-ai ai agent list                                   # → agentUuid
cargo-ai ai chat create --agent-uuid <uuid> --trigger '{"type":"draft"}' --name "Triage"
```

Plays enrol through `batch create`, never `run create` — see [Plays](/plays/overview).

## Next steps

<CardGroup>
  <Card title="Deploying" icon="rocket" href="/deploy/deploying">
    plan, deploy, prune, refresh, import, and destroy.
  </Card>

  <Card title="State & drift" icon="database" href="/deploy/state-and-drift">
    How state tracks live resources and detects out-of-band changes.
  </Card>
</CardGroup>


# Introduction
Source: https://docs.getcargo.ai/index

Cargo is a framework for GTM. Define your entire workspace — connectors, models, tools, agents, and plays — as TypeScript files and deploy it with one command.

Cargo helps revenue teams automate their go-to-market motions with AI: enrich and score records, research accounts, run outbound, and keep the CRM clean.

You build all of it **as code**. A Cargo workspace is a folder of TypeScript files — one `define*` call per resource. The CLI (`cargo-ai`) deploys that folder declaratively, so your connectors, data models, tools, agents, and plays are versioned, diffable, and reproducible.

```bash theme={null}
npm install -g @cargo-ai/cli
cargo-ai login --token <your-api-token>
cargo-ai project init my-workspace
cd my-workspace && cargo-ai project deploy
```

## A workspace at a glance

Each resource type has a home. The `full` starter template lays out the whole surface:

```text theme={null}
my-workspace/
├── package.json
├── cargo.state.json          # written by `project init` — commit it
├── connectors/
│   ├── hubspot.ts            # defineConnector
│   └── openai.ts
├── models/
│   └── contacts.ts           # defineModel — a table sourced from a connector
├── tools/
│   └── enrich.ts             # defineWorkflow + defineTool
├── agents/
│   ├── enricher.ts           # defineAgent (sub-agent)
│   └── sdr.ts                # defineAgent (main agent)
├── plays/
│   └── onboarding.ts         # definePlay — runs a workflow as rows change
├── mcp/
│   └── crm.ts                # defineMcpServer
├── context/                  # defineContext — GTM knowledge base
├── files/                    # defineFile
├── folders/                  # defineFolder
├── workers/                  # defineWorker (hosted edge handlers)
└── apps/                     # defineApp (hosted Vite SPAs)
```

You can understand most Cargo projects by reading that tree.

## The files are the interface

Importing a `.ts` file **is** registration. There is no central manifest to keep in sync: each `define*` call registers a resource as a side effect, and you wire resources together by passing one resource's handle into another.

```ts tools/enrich.ts theme={null}
import { defineTool, defineWorkflow } from "@cargo-ai/cdk";
import { z } from "zod";
import { enricher } from "../agents/enricher";

const enrichFlow = defineWorkflow(
  "enrich-contact",
  {
    input: z.object({ email: z.string() }),
    output: z.object({ company: z.string() }),
    uses: { enricher },
  },
  ({ input, uses }) => ({
    // An agent call resolves to `{ answer, evaluation? }` — read `.answer`.
    company: uses.enricher({ prompt: `Which company owns ${input.email}?` }).answer,
  }),
);

export const enrich = defineTool("enrich", { workflow: enrichFlow });
```

Passing the `enricher` handle into `uses` is what creates the dependency edge — the dependency graph is just your variable graph. Cargo deploys the agent first and injects its real uuid into the tool.

## Deploy declaratively

The CLI reconciles your code against the live workspace. `deploy` creates or updates only what changed and records the result in this project's deploy state.

```bash theme={null}
cargo-ai project plan     # diff against this project's deploy state
cargo-ai project deploy   # create/update; write state
```

Re-deploying with no changes is a no-op. Change one resource and only it updates.

## What to read next

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/get-started/quickstart">
    Install, authenticate, and deploy your first tool in a few minutes.
  </Card>

  <Card title="Project layout" icon="folder-tree" href="/get-started/project-layout">
    The folder-per-resource convention, the loader, and state hygiene.
  </Card>

  <Card title="Connectors" icon="plug" href="/connectors/overview">
    `defineConnector` — link CRMs, warehouses, enrichment, and AI providers.
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/workflows/overview">
    `defineWorkflow` — the TypeScript DSL that backs tools and plays.
  </Card>

  <Card title="Agents" icon="robot" href="/agents/overview">
    `defineAgent` — LLM workers with tools, models, and sub-agents.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/overview">
    Day-to-day operations: run tools, trigger plays, query data.
  </Card>
</CardGroup>

## Prefer the visual builder?

Every resource can also be built in the Cargo web app, and code-first and UI-built resources run identically. The Models, Tools, Agents, Plays, and Mailboxes sections each have a **Using the UI** page, and you can jump into the app any time at [app.getcargo.io](https://app.getcargo.io).


# 6sense
Source: https://docs.getcargo.ai/integration/6sense

Connect 6sense Revenue AI Platform for lead scoring and firmographics in your workflows.

## How to set up 6sense

### Authentication

6sense uses API token authentication:

1. Log in to your 6sense account
2. Navigate to **Settings** → **API** or contact your 6sense admin
3. Generate or obtain your API token
4. Paste the API token in Cargo when connecting

## 6sense capabilities

6sense integration provides access to the Revenue AI Platform for:

* **Account identification**: Identify anonymous website visitors
* **Intent data**: Understand buying signals and intent
* **Firmographics**: Access company data and attributes
* **Lead scoring**: Prioritize accounts based on buying stage

## Integration benefits

* **Anonymous visitor identification**: Know who's on your website
* **Intent signals**: Understand what accounts are researching
* **Buying stage insights**: Know where accounts are in their journey
* **AI-powered predictions**: Leverage 6sense's Revenue AI

## Rate limits

6sense API has a rate limit of 100 requests per minute. Cargo handles rate limiting automatically.

## Best practices

* Use 6sense intent data to prioritize outreach
* Combine with enrichment for complete account profiles
* Set up alerts for accounts entering key buying stages
* Integrate with your CRM for unified account views


# Adyntel
Source: https://docs.getcargo.ai/integration/adyntel

Connect Adyntel to retrieve ad library data across Google, Meta, and LinkedIn in your workflows.

Adyntel provides API access to ad transparency data across major platforms. Use it to research competitor advertising, track campaign activity, or enrich company profiles with ad intelligence.

## How to set up Adyntel

### Authentication

Adyntel requires both an API key and the email address associated with your account:

1. Sign up at [adyntel.com](https://adyntel.com)
2. Navigate to your profile settings under **Integrations**
3. Copy your API key
4. Paste your API key and account email into Cargo when connecting

| Field       | Description                                    |
| ----------- | ---------------------------------------------- |
| **API Key** | Your Adyntel API key                           |
| **Email**   | The email address associated with your account |

## Adyntel actions

### Get Google Ads

Find all Google ads a company is currently running.

**Required fields:**

* **Company domain**: Domain in `company.com` format (no `https://` or `www.` prefix)

**Returns:** A paginated list of Google ads including creative variants, advertiser name, date range, format, and a link to the original Google Ads Transparency page.

**Use case:** Research which Google ad creatives a competitor is running across display and search.

### Get Meta Ads

Find all Facebook and Instagram ads a company is currently running.

**Required fields (one of):**

* **Company domain**: Domain in `company.com` format
* **Facebook page URL**: Direct URL to the company's Facebook page

**Returns:** A paginated list of Meta ads including creative snapshots, body copy, landing pages, platform targeting (Facebook/Instagram), and active status.

**Use case:** Monitor competitor Meta ad campaigns and creative strategy.

### Get LinkedIn Ads

Find all LinkedIn ads a company is currently running.

**Required fields (one of):**

* **Company domain**: Domain in `company.com` format
* **LinkedIn page ID**: Numeric company page ID (e.g. `162479`)

**Returns:** A paginated list of LinkedIn ads including image, carousel, and video creatives, headline copy, commentary text, and creative type.

**Use case:** Track B2B ad messaging and creative formats used by competitors on LinkedIn.

## Best practices

* Use **company domain** when you don't know the platform-specific page ID — Adyntel will resolve it automatically
* Results are paginated; use `continuation_token` to fetch subsequent pages
* Combine all three actions to build a full cross-channel ad intelligence view of any company


# AI Ark
Source: https://docs.getcargo.ai/integration/ai-ark

Connect AI Ark to source companies and people, enrich profiles, find verified emails and mobile phones in your workflows.

## How to set up AI Ark

### Authentication

AI Ark uses API key authentication:

1. Sign up at [ai-ark.com](https://ai-ark.com)
2. Retrieve your API key from your developer portal settings
3. Paste the API key in Cargo when connecting

## AI Ark actions

### Enrich company

Retrieve firmographics for a single company from its domain or LinkedIn URL: industry, employee count, revenue band, HQ location, founding year, and social profiles. Costs 0.01 credits, and a company that cannot be resolved is not charged.

**Inputs:**

| Input        | Description                                          |
| ------------ | ---------------------------------------------------- |
| Domain       | Domain name of the company to enrich (e.g. acme.com) |
| LinkedIn URL | The LinkedIn company URL of the company to enrich    |

Provide one of the two. Revenue is returned as a band rather than a point estimate, and HQ country is returned as a full name rather than an ISO code.

**Use case:** the first step of a company enrichment waterfall, with a broader provider behind it for whatever cannot be resolved.

### Enrich person & find email

Enrich a person's full profile and find their verified email from a LinkedIn URL or an AI-Ark person ID. Emails are verified in real time, and AI Ark does not charge when no valid email is found.

**Inputs:**

| Input            | Description                                 |
| ---------------- | ------------------------------------------- |
| LinkedIn URL     | The LinkedIn profile URL of the person      |
| AI-Ark person ID | The ID returned by a previous People Search |

**Use case:** Waterfall email enrichment with built-in verification.

### Find mobile phone

Find a person's mobile phone number from a LinkedIn URL, or from a company domain and a full name.

**Inputs:**

| Input          | Description                            |
| -------------- | -------------------------------------- |
| LinkedIn URL   | The LinkedIn profile URL of the person |
| Company domain | Used together with the full name       |
| Full name      | Used together with the company domain  |

### Reverse lookup

Find a person's full profile from an email address or a phone number.

### Analyze personality

Analyze a LinkedIn profile to get personality insights (OCEAN and DISC assessments) and tailored selling and hiring communication guidance.

### Search people

Search for people matching person filters (name, title, seniority, location, LinkedIn URL, keywords) and company filters (domain, industry, location, technologies, employee count, revenue).

### Search companies

Search for companies matching company filters, or find lookalikes of up to 5 reference domains.

## AI Ark extractors

### Fetch people

Source people matching person and company filters into a Cargo model. Records unify as contacts through their LinkedIn URL.

### Fetch companies

Source companies matching company filters or lookalike domains into a Cargo model. Records unify as accounts through their domain and LinkedIn URL.


# Airscale
Source: https://docs.getcargo.ai/integration/airscale

Connect Airscale to find people, phone numbers, and emails in your workflows.

## How to set up Airscale

### Authentication

Airscale uses API key authentication:

1. Sign up at [airscale.io](https://airscale.io)
2. Copy your API key from your Airscale dashboard
3. Paste the API key in Cargo when connecting

<Note>
  **Code slugs** — integration slug: `airscale`. Actions: `findPeople`, `findPhone`, `personalEmail`, `reverseEmail`, `reversePhone`. Call them as `integrations.airscale.<action>(...)`.
</Note>

## Airscale actions

### Find people

Search for people by job title, company, location, or keywords.

**Optional fields:**

* **Job titles** / **Excluded job titles**: Job titles to search for or exclude (e.g., CEO, Founder)
* **Company domains** / **Excluded company domains**: Company domains to search for or exclude (e.g., airscale.io)
* **Company LinkedIn URLs** / **Excluded company LinkedIn URLs**: Company LinkedIn URLs to search for or exclude
* **Locations** / **Excluded locations**: Locations to search for or exclude (e.g., FR, US)
* **Keywords** / **Excluded keywords**: Keywords to search across profiles or exclude
* **Limit**: Number of results to return (1-100, default 100)

**Use case:** Build lead lists of people matching your persona at target companies.

### Find phone

Retrieve a phone number given a LinkedIn URL.

**Required fields:**

* **LinkedIn URL**: The LinkedIn profile URL to find the phone number for

**Use case:** Get direct dials for prospects you already have LinkedIn profiles for.

### Find personal email

Find a personal email from a LinkedIn profile URL.

**Required fields:**

* **LinkedIn URL**: The LinkedIn profile URL to find the personal email for

**Use case:** Reach contacts on personal channels when professional email is unavailable.

### Reverse email lookup

Find and enrich a LinkedIn profile from a professional email.

**Required fields:**

* **Email**: The professional email address to look up

**Use case:** Turn inbound signups or CRM emails back into full LinkedIn profiles.

### Reverse phone lookup

Find and enrich a LinkedIn profile from a mobile number.

**Required fields:**

* **Mobile phone**: The mobile phone number to look up (include country code, e.g. +33610607076)

**Use case:** Identify who is behind a phone number captured from calls or forms.

## Best practices

* Combine **Find people** with **Find phone** or **Find personal email** to go from search to contactable leads
* Include the country code in phone numbers for reverse phone lookups
* Results are cacheable in Cargo — avoid redundant lookups for the same profile


# Albacross
Source: https://docs.getcargo.ai/integration/albacross

Identify website visitors and enrich IP addresses with company data

Albacross is a website visitor identification platform that reveals which companies are visiting your website. The Cargo integration enables you to enrich IP addresses and sync website visit data.

## Authentication

Connect to Albacross using your API key.

### Connection details

| Field       | Description            |
| ----------- | ---------------------- |
| **API Key** | Your Albacross API key |

***

## Albacross actions

### Enrich IP

Identify the company behind an IP address.

**Configuration**

| Field     | Description              |
| --------- | ------------------------ |
| **IP V4** | IPv4 address to identify |

**Returns**

Company information including name, domain, industry, employee count, and more.

***

## Data models

### Listen website visits

Receive real-time notifications when companies visit your website.

**Configuration**

No additional configuration required. Albacross will push visit data to Cargo automatically.

**Data returned**

Each visit includes:

* Company information (name, domain, industry)
* Visit details (pages viewed, time on site)
* Contact event data for workflow triggering

***

## Use cases

<AccordionGroup>
  <Accordion title="Account-based marketing" icon="bullseye">
    Identify target accounts visiting your website and trigger personalized campaigns.
  </Accordion>

  <Accordion title="Sales alerts" icon="bell">
    Notify sales reps when their accounts are actively researching your product.
  </Accordion>

  <Accordion title="Lead scoring" icon="chart-line">
    Boost lead scores based on website engagement from identified companies.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Filter by ICP** - Focus on visits from companies matching your ideal customer profile
2. **Track high-intent pages** - Prioritize visits to pricing, demo, or product pages
3. **Combine with enrichment** - Layer Albacross data with other enrichment sources for complete profiles


# Amplemarket
Source: https://docs.getcargo.ai/integration/amplemarket

Connect Amplemarket for sales automation and outreach

Amplemarket is an AI-powered sales automation platform that helps sales teams find, engage, and convert leads. The Cargo integration enables you to connect your Amplemarket sequences and mailboxes.

## Authentication

Connect to Amplemarket using your API key.

### Connection details

| Field       | Description              |
| ----------- | ------------------------ |
| **API Key** | Your Amplemarket API key |

<Tip>
  Find your API key in your Amplemarket account settings under the API section.
</Tip>

***

## Use cases

<AccordionGroup>
  <Accordion title="Sequence management" icon="list-check">
    Access your Amplemarket sequences for workflow automation.
  </Accordion>

  <Accordion title="Mailbox integration" icon="envelope">
    Connect with your configured mailboxes for outreach campaigns.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Validate leads** - Ensure lead data is complete before adding to sequences
2. **Monitor deliverability** - Track email performance through Amplemarket's dashboard
3. **Use personalization** - Pass custom fields from Cargo to personalize outreach


# Amplitude
Source: https://docs.getcargo.ai/integration/amplitude

Connect Amplitude to pull product analytics events into your workflows.

## How to set up Amplitude

### Authentication

Amplitude requires API credentials:

1. Log in to your Amplitude account
2. Navigate to **Settings** → **Projects** → Select your project
3. Find your credentials:
   * **Region**: US or EU (based on your data location)
   * **API Key**: Your project API key
   * **Secret Key**: Your project secret key
4. Enter all credentials in Cargo when connecting

## Amplitude data models

### Fetch events

Pull product analytics events from Amplitude into Cargo.

**Configuration:**

* **Start date**: Begin fetching events from this date

**Features:**

* Incremental sync (only new events since last sync)
* Minimum 12-hour sync interval
* Unifies as contact events

**Data includes:**

* Event name
* User ID
* Event properties
* Timestamp
* Session data

## Event data structure

Amplitude events typically include:

| Field             | Description             |
| ----------------- | ----------------------- |
| event\_type       | Name of the event       |
| user\_id          | User identifier         |
| event\_time       | When the event occurred |
| event\_properties | Custom event data       |
| user\_properties  | User attributes         |
| platform          | Device platform         |
| country           | User's country          |
| city              | User's city             |

## Best practices

* Define key activation events in Amplitude
* Use consistent user IDs that map to your CRM
* Set meaningful sync intervals based on your use case
* Combine Amplitude data with enrichment for complete profiles
* Build lead scoring models using product engagement signals

## Use cases

* **Lead qualification**: Score leads based on product usage
* **Sales enablement**: Surface product usage data to sales
* **Customer success**: Monitor account health
* **Marketing**: Trigger campaigns based on behavior


# Anthropic
Source: https://docs.getcargo.ai/integration/anthropic

This page outlines how to use the Anthropic integration for AI-powered actions in Cargo.

Anthropic builds reliable, interpretable AI systems. Claude, their AI assistant, excels at thoughtful dialogue, content creation, complex reasoning, and coding. Cargo's native integration with Anthropic allows you to use Claude models directly in your workflows.

## How to set up Anthropic

You can use Anthropic in two ways:

1. **Cargo credits** – Use Claude through Cargo's managed integration
2. **Your own API key** – Connect your Anthropic account

### Connection details

| Field       | Description            |
| ----------- | ---------------------- |
| **API Key** | Your Anthropic API key |

<Tip>Find your API key in the Anthropic Console under **API Keys**.</Tip>

***

## Anthropic actions

### Instruct

Send a prompt to a Claude model and receive a text response.

**Use cases**

* **Content generation** – Generate personalized emails and messages
* **Classification** – Categorize text into predefined categories
* **Summarization** – Summarize long documents or conversations
* **Data extraction** – Extract structured information from text
* **Analysis** – Analyze sentiment, intent, or other properties
* **Reasoning** – Complex multi-step problem solving

**Configuration**

| Field               | Description                     |
| ------------------- | ------------------------------- |
| **Model**           | Select the Claude model to use  |
| **Prompt**          | The prompt to send to the model |
| **System prompt**   | Optional system instructions    |
| **Maximum tokens**  | Limit output length             |
| **Temperature**     | Control randomness (0-1)        |
| **With web search** | Enable web search capabilities  |

### Available models

The available Claude models — and their per-model credit costs — evolve with Anthropic's lineup, so the action's **Model** dropdown in the workspace is always the authoritative list. From the terminal:

```bash theme={null}
cargo-ai connection integration get anthropic
```

**Picking a model:**

* **Opus** — the most powerful tier: complex reasoning, advanced coding, creative work (highest credit cost)
* **Sonnet** — the best balance of intelligence and cost for most tasks, including agents (start here)
* **Haiku** — fast, low-cost inference for high-volume, low-latency work

### Advanced settings

#### System prompt

Set instructions that guide Claude's behavior:

* Define the model's role or persona
* Set output format guidelines
* Provide context about your use case
* Establish constraints or rules

#### Temperature

Control the randomness of outputs:

| Temperature | Behavior              |
| ----------- | --------------------- |
| **0**       | Most deterministic    |
| **0.3-0.5** | Balanced              |
| **0.7-1**   | More creative, varied |

#### Web search

Enable Claude to search the web for current information:

* Real-time data lookups
* Current events research
* Fact verification


# Anymail Finder
Source: https://docs.getcargo.ai/integration/anymail-finder

Connect Anymail Finder to discover and verify email addresses in your workflows.

## How to set up Anymail Finder

### Authentication

Anymail Finder uses API key authentication:

1. Sign up at [anymailfinder.com](https://anymailfinder.com)
2. Navigate to your API settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## Anymail Finder actions

### Find email

Find a person's email address using their name and company.

**Required fields:**

* **Domain name**: Company domain
* **Company name**: Company name

**Optional fields:**

* **First name**: Person's first name
* **Last name**: Person's last name
* **Full name**: Person's full name (alternative to first/last)

**Use case:** Discover professional email addresses when you have name and company info.

### Find email from LinkedIn

Find a person's email using their LinkedIn profile URL.

**Required fields:**

* **LinkedIn URL**: Person's LinkedIn profile URL

**Use case:** Convert LinkedIn profiles to email addresses for outreach.

### Search emails

Find all email addresses at a company or domain.

**Input fields:**

* **Domain name**: Company domain (recommended)
* **Company name**: Company name

**Use case:** Build contact lists for account-based campaigns.

### Verify email

Check if an email address is valid and deliverable.

**Required fields:**

* **Email**: The email address to verify

**Use case:** Validate emails before sending campaigns.

## Best practices

* Always provide domain when available (more accurate than company name alone)
* Use LinkedIn URL when you have it - often most reliable
* Verify emails before adding to outreach campaigns
* Search company emails to build comprehensive account lists
* Combine first name + last name for better individual matching


# Apify
Source: https://docs.getcargo.ai/integration/apify

This page outlines how to use the Apify integration for web scraping and automation in Cargo.

Apify is a web scraping and automation platform that provides thousands of ready-made scrapers (called Actors) for popular websites. Cargo's native integration with Apify allows you to run actors, execute pre-configured tasks, and fetch scraped data directly from your workflows.

## How to set up Apify

To connect Apify, you need an API token from your Apify account. This integration requires your own Apify account and API credentials.

### Connection details

| Field         | Description                                |
| ------------- | ------------------------------------------ |
| **API Token** | Your Apify API token from account settings |

<Tip>Get your API token from the [Apify Console](https://console.apify.com/) under Settings → Integrations.</Tip>

***

## Apify actions

### Run Actor

Execute any Apify actor with custom input parameters.

**Use cases**

* **Web scraping** – Run scrapers for LinkedIn, Twitter, Instagram, Amazon, etc.
* **Data extraction** – Extract structured data from any website
* **Lead generation** – Scrape contact information from directories
* **Competitive analysis** – Monitor competitor websites and pricing

**Configuration**

| Field           | Description                                     |
| --------------- | ----------------------------------------------- |
| **Actor**       | Select from your available actors               |
| **Input**       | JSON input parameters for the actor (optional)  |
| **Memory (MB)** | Memory limit for the run (default: 2048 MB)     |
| **Timeout**     | Maximum run duration in seconds (default: 3600) |

**Output**

| Field               | Description                            |
| ------------------- | -------------------------------------- |
| **runId**           | Unique identifier for the run          |
| **status**          | Final status (SUCCEEDED, FAILED, etc.) |
| **datasetId**       | ID of the dataset containing results   |
| **keyValueStoreId** | ID of the key-value store              |
| **startedAt**       | When the run started                   |
| **finishedAt**      | When the run completed                 |

<Info>Use the `datasetId` from the output with the Get Dataset extractor to retrieve the scraped data.</Info>

### Run Task

Execute a pre-configured Apify task. Tasks are saved actor configurations that can be reused.

**Use cases**

* **Recurring scrapes** – Run the same scraping job repeatedly
* **Standardized workflows** – Use pre-configured settings for consistent results
* **Team collaboration** – Share task configurations across team members

**Configuration**

| Field              | Description                                     |
| ------------------ | ----------------------------------------------- |
| **Task**           | Select from your available tasks                |
| **Input Override** | JSON input to override task defaults (optional) |
| **Memory (MB)**    | Memory limit for the run (optional)             |
| **Timeout**        | Maximum run duration in seconds (optional)      |

**Output**

Same as Run Actor.

***

## Apify data models

Create data models from Apify datasets to power your workflows.

### Get Dataset

Fetch items from an Apify dataset. Use this to retrieve results from a previous actor or task run.

**Configuration**

| Field          | Description                                        |
| -------------- | -------------------------------------------------- |
| **Dataset ID** | The ID of the dataset (from a previous run)        |
| **Limit**      | Maximum items to fetch (default: 1000)             |
| **Clean data** | Remove empty items and hidden fields (default: on) |

<Tip>The dataset schema is automatically detected from the data, so columns will match whatever the actor returns.</Tip>

***

## Common workflows

### Scrape and enrich leads

1. **Run Actor** – Use a LinkedIn scraper to extract company data
2. **Get Dataset** – Fetch the scraped results
3. **Enrich** – Use other integrations to add contact information

### Monitor competitors

1. **Run Task** – Execute a pre-configured price monitoring scraper
2. **Get Dataset** – Retrieve the latest pricing data
3. **Compare** – Analyze changes against your own pricing

### Build prospect lists

1. **Run Actor** – Scrape a directory or database
2. **Get Dataset** – Pull the extracted contacts
3. **Push to CRM** – Send qualified leads to HubSpot or Salesforce

***

## Popular Apify Actors

| Actor                     | Description                            |
| ------------------------- | -------------------------------------- |
| **Web Scraper**           | General-purpose website scraper        |
| **Google Search Scraper** | Extract Google search results          |
| **LinkedIn Scraper**      | Scrape LinkedIn profiles and companies |
| **Instagram Scraper**     | Extract posts, profiles, and hashtags  |
| **Amazon Scraper**        | Product data from Amazon               |
| **Twitter Scraper**       | Tweets, profiles, and trends           |

<Info>Browse thousands of actors in the [Apify Store](https://apify.com/store).</Info>


# Apollo.io
Source: https://docs.getcargo.ai/integration/apolloio

Connect Apollo.io to enrich contacts, search prospects, and manage sales engagement in your workflows.

## How to set up Apollo.io

### Authentication

Apollo.io uses API key authentication:

1. Log in to your Apollo.io account
2. Navigate to **Settings** → **Integrations** → **API Keys**
3. Create a new API key or use an existing one
4. Copy the API key and paste it in Cargo when connecting

## Apollo.io actions

### Enrich person

Get detailed information about a person including email and phone.

**Optional fields:**

* **ID**: Apollo person ID
* **First name**: Person's first name
* **Last name**: Person's last name
* **Organization name**: Company name
* **Email**: Known email address
* **Email MD5/SHA256**: Hashed email for matching
* **Domain**: Company domain
* **LinkedIn URL**: Person's LinkedIn profile URL
* **Reveal personal emails**: Include personal email addresses
* **Reveal phone number**: Include phone numbers (uses additional credits)

**Use cases:**

* Enrich inbound leads with contact details
* Find email addresses for outbound prospects
* Verify and update contact information

### Enrich organization

Get company information. Provide at least one of the identifiers below; Apollo matches on whichever you supply.

**Fields:**

* **Domain**: Company domain, without `www.` or the `@` symbol
* **LinkedIn URL**: Company LinkedIn page
* **Name**: Company name
* **Website**: Full website URL

**Returns:** Company firmographics, size, industry, technologies, and more.

### Search people

Find prospects matching specific criteria.

**Person filters:**

* **Person titles**: Job titles to search for
* **Include similar titles**: Also match titles Apollo considers similar; turn off to match your list exactly
* **Person seniorities**: owner, founder, c\_suite, partner, vp, head, director, manager, senior, entry, intern
* **Person locations**: Geographic locations
* **Contact email status**: verified, unverified, likely\_to\_engage, unavailable
* **Keywords**: Search across all fields
* **Prospected by current team**: Filter by team prospecting history

**Employer filters:**

* **Organization domains**: Specific company domains
* **Organization IDs**: Apollo company IDs
* **Organization locations**: Company headquarters locations
* **Organization employee ranges**: Company size filters
* **Organization revenue range**: Minimum and maximum annual revenue
* **Technologies**: Match employers using any of, all of, or none of a set of Apollo technology UIDs
* **Hiring signals**: Job titles being recruited for, job locations, number of open postings, and when they were posted

**Enrichment:** Apollo's people search returns obfuscated previews with no email. Enable **Should enrich** to resolve every match into a full profile, which consumes Apollo credits.

**Use case:** Build targeted prospect lists based on ICP criteria.

### Search organizations

Find companies matching specific criteria.

**Filters:**

* **Organization name**: Company name search
* **Organization domains**: Specific company domains
* **Organization IDs**: Apollo company IDs
* **Keyword tags**: Industry and topic tags
* **Organization locations**: Company locations
* **Excluded organization locations**: Exclude locations
* **Organization employee ranges**: Company size
* **Revenue range**: Minimum and maximum annual revenue
* **Funding**: Latest round amount, total raised, and latest round date
* **Technologies**: Companies currently using any of a set of Apollo technology UIDs
* **Hiring signals**: Job titles being recruited for, job locations, number of open postings, and when they were posted

### Search contacts

Search your existing Apollo contacts.

**Filters:**

* **Contact stages**: Filter by pipeline stage
* **Keywords**: Search across contact fields
* **Sort by field**: Order results by activity date, email opens, clicks, created/updated dates
* **Sort ascending**: Sort direction

### Search email accounts

List email accounts available for sequences.

**Optional fields:**

* **User ID**: Filter by specific user

### Create contact

Add a new contact to your Apollo database.

**Required fields:**

* **Email**: Contact's email address

**Optional fields:**

* **Contact stage**: Pipeline stage
* **Owner**: Assign to a user
* **Mappings**: Standard fields (first name, last name, title, phone numbers, etc.)
* **Custom mappings**: Custom field values

### Upsert contact

Create a new contact or update existing (matched by email).

Same fields as Create contact. Prevents duplicates when syncing from external sources.

### Update contact

Update an existing contact by ID.

**Required fields:**

* **ID**: Apollo contact ID

**Optional fields:**

* Same as Create contact

### Add contact to sequence

Enroll a contact in an email sequence.

**Required fields:**

* **Contact ID**: The Apollo contact ID
* **Sequence ID**: Select the sequence
* **Email account ID**: The email account to send from

**Optional fields:**

* **Options**: Additional enrollment options
* **User ID**: Assign to specific user

**Use case:** Automatically enroll qualified leads in outreach sequences.

### Remove contact from sequence

Remove a contact from an active sequence.

**Required fields:**

* **Contact ID**: The Apollo contact ID
* **Sequence ID**: The sequence to remove from
* **Mode**: Choose action:
  * Mark as finished
  * Remove
  * Stop

## Apollo.io data models

### Fetch contacts

Pull contacts from Apollo.io into Cargo.

**Configuration:**

* **Contact stages**: Filter by specific stages

**Features:**

* Incremental sync (only new/updated contacts)
* Minimum 30-minute sync interval
* Unifies by LinkedIn URL, LinkedIn UID, or email

### Fetch accounts

Pull accounts from Apollo.io into Cargo.

**Configuration:**

* **Account stages**: Filter by specific stages

**Features:**

* Incremental sync
* Minimum 30-minute sync interval
* Unifies by domain or LinkedIn URL

### Fetch people

Build a contact model from Apollo's people database rather than from your own Apollo CRM.

**Configuration:**

* The same person, employer, technology, and hiring filters as the **Search people** action
* **Limit**: defaults to 500, up to 50,000

**Features:**

* Stores Apollo's search results as they come back. These are partial previews — no email, LinkedIn URL, or full last name — so run the stored rows through the **Enrich person** action to resolve them into full profiles.
* Works with Cargo credits or your own API key, with no credit cost either way: Apollo's people search is free.

### Fetch organizations

Build an account model from Apollo's company database rather than from your own Apollo CRM.

**Configuration:**

* The same firmographic, funding, technology, and hiring filters as the **Search organizations** action
* **Limit**: defaults to 500, up to 50,000

**Features:**

* Unifies by domain or LinkedIn URL
* Returns both companies new to you and companies you already track as Apollo accounts. Apollo splits these across two buckets internally; both are stored, with accounts mapped onto the organization shape.
* Works with Cargo credits or your own API key. Apollo charges 1 of its credits per page of up to 100 organization search results, so on Cargo credits each record costs 0.01 credits.

<Note>
  Firmographics that Apollo only hydrates on the search side — industry,
  revenue, funding — come back empty for companies already saved as accounts in
  your Apollo CRM. Run **Enrich organization** on those rows to fill them in.
</Note>

<Note>
  Apollo stops serving search results past 50,000 records however the query is
  paginated. Narrow your filters rather than raising the limit if you need
  deeper coverage.
</Note>

## Credits

Apollo.io is billable with Cargo credits, so you can use it without your own Apollo account. One Apollo credit converts to one Cargo credit.

* **Enrich person**: 1 credit (9 credits with phone number reveal, which costs Apollo 8 extra credits)
* **Enrich organization**: 1 credit
* **Search people**: free on its own; enabling **Should enrich** costs 1 credit per enriched result
* **Search organizations**: 0.01 credits per result, since Apollo charges 1 of its credits per page of up to 100 organization search results
* **Fetch people**: no credit cost — it stores unenriched search previews
* **Fetch organizations**: 0.01 credits per record

Cargo tracks credit usage and supports caching to optimize costs.

## Rate limits

Apollo.io API has a rate limit of 400 requests per hour. Cargo automatically handles rate limiting with retry logic to ensure reliable execution.


# Appfigures
Source: https://docs.getcargo.ai/integration/appfigures

Search app store products and get revenue estimates with Appfigures

Appfigures is an app analytics platform that provides app store data, revenue estimates, and download metrics. The Cargo integration enables you to search for apps and retrieve performance data.

## Authentication

Connect to Appfigures using your access token.

### Connection details

| Field            | Description                  |
| ---------------- | ---------------------------- |
| **Access token** | Your Appfigures access token |

***

## Appfigures actions

### Search products

Search for products in app stores.

**Configuration**

| Field           | Description                               |
| --------------- | ----------------------------------------- |
| **Term**        | Product or developer name to search       |
| **Storefronts** | Filter by app stores (iOS, Android, etc.) |
| **Limit**       | Maximum number of results                 |

<Tip>
  Prefix your search with `@name=` or `@developer=` to search specific fields only.
</Tip>

### Get product estimates report

Retrieve revenue and download estimates for a specific product.

**Configuration**

| Field          | Description                            |
| -------------- | -------------------------------------- |
| **Product ID** | The Appfigures product ID              |
| **Start date** | Start date for the report (YYYY-MM-DD) |
| **End date**   | End date for the report (YYYY-MM-DD)   |

***

## Use cases

<AccordionGroup>
  <Accordion title="Competitive intelligence" icon="chart-bar">
    Track competitor app performance and revenue estimates.
  </Accordion>

  <Accordion title="Market research" icon="magnifying-glass">
    Discover apps in specific categories or by developer.
  </Accordion>

  <Accordion title="Investment research" icon="chart-line">
    Analyze app revenue trends for investment decisions.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use specific search terms** - More specific queries yield better results
2. **Filter by storefront** - Focus on relevant app stores for your analysis
3. **Set date ranges** - Define specific periods for accurate estimates


# Attio
Source: https://docs.getcargo.ai/integration/attio

This page outlines how to use the Attio integration to pull and manage CRM data in Cargo.

Attio is a modern customer relationship management tool that's easy to get started with and scales with your team's operations. Cargo's native integration with Attio allows you to both pull data from the CRM as part of data models, and write or delete data from all CRM objects to maintain it.

## How to set up Attio

<div>
  <iframe title="Setup a data model" />
</div>

Attio uses your logged-in instance to establish the sync with Cargo. During connection, you'll be asked to authorize Cargo with the following permissions:

<AccordionGroup>
  <Accordion title="Required permissions">
    * Read and write records - Read object configuration - Read list entries -
      Read and write comments - Read and write notes - Read and write tasks - Read
      user management settings - Read list configuration
  </Accordion>
</AccordionGroup>

Once redirected and the connector is created, you can:

* **Set up an Attio data model** — Create data models from your Attio objects to trigger Plays and power model search actions.
  <img alt="Attio data model" />
* **Use Attio in workflows** — Choose **Attio** from the node catalog within a **Play**, **Tool**, or **Agent**.
  <img alt="Attio catalog" />

***

## Attio actions

<Tip>
  All Attio actions support People, Companies, Deals, and any custom objects
  you've created in your Attio workspace.
</Tip>

### Insert record

<div>
  <iframe title="Setup a data model" />
</div>

Insert a new record into Attio.

**Use cases**

* **Lead capture** – Create new leads from various sources and channels
* **Contact creation** – Add new contacts from forms, events, or imports
* **Company creation** – Add new companies from forms, events, or imports

### Find record

Retrieve a single record from Attio by its unique ID.

**Use cases**

* **Record lookup** – Get specific record details for processing workflows
* **Data validation** – Verify record existence before performing operations

### Match record

Check if a record exists in Attio based on matching criteria.

**Use cases**

* **Duplicate prevention** – Avoid creating duplicate records
* **Smart routing** – Route records based on existing data

<Info>
  Use **Match record** before **Insert record** to implement an upsert pattern
  for single records.
</Info>

### Find records

Find records matching the given criteria. Define multiple matching criteria—the action searches for records that match any of the provided values. Empty values are automatically skipped.

**Use cases**

* **Multi-identifier matching** – Search by domain, LinkedIn URL, or company name
* **Flexible lookups** – Find records using whichever identifiers are available
* **Data quality handling** – Provide multiple identifiers to maximize match rates

**Example configuration**

| Attribute  | Value                            |
| ---------- | -------------------------------- |
| `domains`  | `{{nodes.start.company_domain}}` |
| `linkedin` | `{{nodes.start.linkedin_url}}`   |
| `name`     | `{{nodes.start.company_name}}`   |

<Tip>
  Empty values are automatically skipped, so you can provide all available
  identifiers without worrying about null checks.
</Tip>

### Search records

Retrieve multiple records from Attio based on search criteria.

**Use cases**

* **Advanced filtering** – Find records meeting specific criteria
* **Bulk operations** – Retrieve multiple records for processing inside a group node

### Update record

Update an existing record in Attio.

**Use cases**

* **Data enrichment** – Keep record information current and accurate
* **Lifecycle management** – Update record stages and statuses

### Upsert records

Upsert multiple records into Attio (insert or update based on matching criteria).

**Use cases**

* **Bulk data operations** – Insert records in bulk while avoiding duplicates
* **Data synchronization** – Keep external systems synchronized with Attio

<Warning>
  Upsert operations will match on the fields you specify. Ensure your matching
  criteria is unique to avoid unintended updates.
</Warning>

### Merge records

Merge two records of the same object into a new Attio record. When both source records have a value for the same attribute, the primary record's value takes precedence. The secondary record's values fill attributes that are empty on the primary record.

**Configuration**

* **Object type**: Select the object shared by both records
* **Primary record ID**: The record whose values take precedence
* **Secondary record ID**: The record whose values fill missing primary values

<Warning>
  A merge creates a new record ID and makes both original records inaccessible.
  The operation is not idempotent, so repeating it returns an error. Large
  merges may be applied asynchronously: the returned record ID can temporarily
  return Attio's `merge_in_progress` error when read immediately. This endpoint
  is currently in beta.
</Warning>

### Delete record

Delete a record from Attio.

**Use cases**

* **Data cleanup** – Remove outdated or incorrect records programmatically or in batches

***

## Attio data models

Cargo allows you to create data models on top of your Attio CRM data that can be used to trigger Plays and power model search actions.

### Creating Attio data models

<div>
  <iframe title="Setup a data model" />
</div>

| Field           | Description                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------- |
| **Name**        | Choose a descriptive name for your data model (required)                                     |
| **Slug**        | Set a unique identifier that cannot be changed once created (required)                       |
| **Object Type** | Select the Attio object type you want to model (People, Companies, Deals, or custom objects) |

### Object types available

<AccordionGroup>
  <Accordion title="Deal models" icon="handshake">
    **Use cases** - Track opportunities, pipeline stages, and deal progression -
    Monitor deal velocity, conversion rates, and forecasting - Analyze win/loss
    patterns and sales performance
  </Accordion>

  <Accordion title="Company models" icon="building">
    **Use cases** - Manage company records with domains, descriptions, and team
    information - Track company categories, locations, and relationships -
    Monitor company engagement and lifecycle stages
  </Accordion>

  <Accordion title="Person models" icon="user">
    **Use cases** - Handle contact and lead information - Track individual
    engagement and communication history - Manage contact lifecycle and
    qualification status
  </Accordion>
</AccordionGroup>

<Tip>
  You can also model any **custom objects** you've created in Attio, giving you
  full flexibility to work with your unique data structures.
</Tip>


# Azure OpenAI
Source: https://docs.getcargo.ai/integration/azure-open-ai

This page outlines how to use the Azure OpenAI integration for AI-powered actions in Cargo.

Azure OpenAI Service provides access to OpenAI's powerful language models through Microsoft Azure's enterprise-grade infrastructure. This integration allows you to use your Azure OpenAI deployments directly in Cargo workflows, ideal for organizations with compliance, data residency, or security requirements.

## How to set up Azure OpenAI

Azure OpenAI requires your own Azure credentials (BYOC). Cargo credits are not available for this integration.

### Prerequisites

Before connecting, ensure you have:

1. An active Azure subscription
2. An Azure OpenAI resource created in the Azure Portal
3. At least one model deployment in your Azure OpenAI resource

### Connection details

| Field             | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| **Resource Name** | Your Azure OpenAI resource name (e.g., `my-company-openai`) |
| **API Key**       | Your Azure OpenAI API key from the Azure Portal             |
| **API Version**   | Optional. Defaults to `2024-08-01-preview`                  |

### Finding your credentials

#### Resource Name

1. Go to the [Azure Portal](https://portal.azure.com)
2. Navigate to your Azure OpenAI resource
3. The resource name is in the overview page and part of your endpoint URL
   * If your endpoint is `https://my-company-openai.openai.azure.com/`, your resource name is `my-company-openai`

#### API Key

1. In the Azure Portal, navigate to your Azure OpenAI resource
2. Click **Keys and Endpoint** under "Resource Management"
3. Copy **KEY 1** or **KEY 2**

<Tip>
  Find your API key and endpoint in the Azure Portal under your Azure OpenAI resource → **Keys and Endpoint**.
</Tip>

***

## Azure OpenAI actions

### Instruct

Send a prompt to an Azure OpenAI deployment and receive a text response.

**Use cases**

* **Content generation** – Generate personalized emails, messages, or content
* **Classification** – Categorize text into predefined categories
* **Summarization** – Summarize long text into concise summaries
* **Data extraction** – Extract structured data from unstructured text
* **Translation** – Translate text between languages
* **Analysis** – Analyze sentiment, intent, or other text properties

**Configuration**

| Field               | Description                                             |
| ------------------- | ------------------------------------------------------- |
| **Deployment Name** | The name of your Azure OpenAI deployment                |
| **Prompt**          | The prompt to send to the model                         |
| **System prompt**   | Optional system instructions                            |
| **Maximum tokens**  | Limit output length                                     |
| **Temperature**     | Control randomness (0 = deterministic, 2 = very random) |
| **Response format** | Text, JSON object, or JSON schema                       |

<Warning>
  Azure OpenAI uses **deployment names** instead of model names. You define these names when deploying models in the Azure Portal.
</Warning>

### Understanding deployments

Unlike standard OpenAI where you select models like `gpt-4o`, Azure OpenAI requires you to:

1. Deploy a model in the Azure Portal
2. Give it a custom deployment name (e.g., `my-gpt4o-deployment`)
3. Use that deployment name in Cargo

To find your deployment names:

1. Go to your Azure OpenAI resource in the Azure Portal
2. Click **Model deployments** in the left sidebar
3. Note the **Deployment name** for each model

### Response formats

Control how the model returns its response:

| Format          | Description                                       |
| --------------- | ------------------------------------------------- |
| **Text**        | Free-form text response (default)                 |
| **JSON object** | Response formatted as valid JSON                  |
| **JSON schema** | Response validated against a specific JSON schema |

<Tip>
  Use **JSON schema** when you need structured output with specific fields.
  Define your schema to ensure consistent, parseable responses.
</Tip>

#### Example JSON schema

```json theme={null}
{
  "type": "object",
  "properties": {
    "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
    "confidence": { "type": "number" },
    "summary": { "type": "string" }
  },
  "additionalProperties": false,
  "required": ["sentiment", "confidence", "summary"]
}
```

### Advanced settings

#### System prompt

Set instructions that guide the model's behavior across all prompts:

* Define the model's role or persona
* Set output format guidelines
* Provide context about your use case
* Establish constraints or rules

#### Temperature

Control the randomness of outputs:

| Temperature | Behavior                               |
| ----------- | -------------------------------------- |
| **0**       | Most deterministic, consistent outputs |
| **0.5-1**   | Balanced creativity and consistency    |
| **1-2**     | More creative, varied outputs          |

<Warning>
  For tasks requiring consistency (classification, extraction), use low
  temperature (0-0.3). For creative tasks (content generation), use higher
  temperature (0.7-1).
</Warning>

***

## API versions

Azure OpenAI requires an API version. Cargo defaults to `2024-08-01-preview`. If you need specific features, you can override it:

| Version              | Description              |
| -------------------- | ------------------------ |
| `2024-08-01-preview` | Latest preview (default) |
| `2024-06-01`         | Latest stable version    |
| `2024-02-01`         | Older stable version     |

***

## Troubleshooting

### "DeploymentNotFound" error

The deployment name you specified doesn't exist. Verify:

* The deployment name matches exactly as shown in the Azure Portal
* The deployment is in the same resource you configured

### "Unauthorized" error

Your credentials may be incorrect. Check that:

* Your API key is correct and hasn't been regenerated
* Your Azure OpenAI resource is active
* The API key has access to the specified resource


# BetterContact
Source: https://docs.getcargo.ai/integration/bettercontact

Connect BetterContact for waterfall enrichment to find emails and phones in your workflows.

## How to set up BetterContact

### Authentication

BetterContact uses API key authentication:

1. Sign up at [bettercontact.rocks](https://bettercontact.rocks)
2. Navigate to your API settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## BetterContact actions

### Find email

Find a person's email address using multiple data sources (waterfall enrichment).

**Input fields (provide as many as available):**

* **First name**: Person's first name
* **Last name**: Person's last name
* **Company**: Company name
* **Company domain**: Company domain
* **LinkedIn URL**: Person's LinkedIn profile URL

**Use case:** Waterfall enrichment checks multiple providers to maximize match rates.

### Find phone

Find a person's phone number using multiple data sources.

**Input fields (provide as many as available):**

* **First name**: Person's first name
* **Last name**: Person's last name
* **Company**: Company name
* **Company domain**: Company domain
* **LinkedIn URL**: Person's LinkedIn profile URL

**Use case:** Maximize phone number discovery through waterfall approach.

## How waterfall enrichment works

BetterContact automatically queries multiple data providers in sequence until a match is found. This approach:

* **Maximizes coverage**: If one provider fails, others are tried
* **Improves accuracy**: Results are cross-validated
* **Simplifies workflows**: One integration instead of many

## Retry behavior

BetterContact actions include extensive retry logic:

* Maximum 20 retry attempts
* 60-second intervals between retries
* Handles provider rate limits automatically

This ensures reliable results even when individual providers are slow.

## Rate limits

BetterContact API has a rate limit of 60 requests per minute. Cargo handles rate limiting automatically.

## Best practices

* Provide as many input fields as possible for best results
* LinkedIn URL often provides the best matching
* Include company domain for higher accuracy
* Use waterfall as a fallback for other enrichment sources
* Cache results to avoid redundant lookups


# BigQuery
Source: https://docs.getcargo.ai/integration/big-query

This page outlines how to use the BigQuery integration to create and manage your data warehouse in Cargo.

BigQuery is Google Cloud's fully managed, serverless data warehouse that enables super-fast SQL queries. Cargo's native integration with BigQuery allows you to connect your data warehouse, create data models, and execute SQL operations directly in your workflows.

<Note>
  To use BigQuery as your **system of record**, follow the full setup guide:
  [Set up Cargo on BigQuery](/reference/system-of-record/bigquery). It covers
  enabling the required Google APIs, the storage bucket, the service account,
  and the SOR settings form.
</Note>

## How to set up BigQuery

### Prerequisites

Before connecting BigQuery to Cargo, ensure you have:

* An active Google Cloud Project with billing enabled
* BigQuery API enabled
* A service account with appropriate permissions

### Creating a Service Account

To connect Cargo to BigQuery, you need a service account with the necessary permissions:

<Tabs>
  <Tab title="Console">
    1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
    2. Navigate to **IAM & Admin** → **Service Accounts**
    3. Click **Create service account**
    4. Give the service account a name (e.g., `cargo-bigquery`)
    5. Grant the following roles:
       * `BigQuery Data Editor` – Read and write data in BigQuery tables
       * `BigQuery Job User` – Run queries and jobs
    6. Click **Done**
    7. Click on the newly created service account
    8. Go to the **Keys** tab
    9. Click **Add Key** → **Create new key** → **JSON**
    10. Save the downloaded JSON file securely—you'll need its contents for the connection
  </Tab>

  <Tab title="CLI">
    **Create the service account:**

    ```bash theme={null}
    gcloud iam service-accounts create cargo-bigquery \
        --display-name="Cargo BigQuery Service Account"
    ```

    **Grant BigQuery permissions:**

    ```bash theme={null}
    gcloud projects add-iam-policy-binding your-project-id \
        --member="serviceAccount:cargo-bigquery@your-project-id.iam.gserviceaccount.com" \
        --role="roles/bigquery.dataEditor"

    gcloud projects add-iam-policy-binding your-project-id \
        --member="serviceAccount:cargo-bigquery@your-project-id.iam.gserviceaccount.com" \
        --role="roles/bigquery.jobUser"
    ```

    **Create and download a key file:**

    ```bash theme={null}
    gcloud iam service-accounts keys create cargo-bigquery-key.json \
        --iam-account=cargo-bigquery@your-project-id.iam.gserviceaccount.com
    ```
  </Tab>
</Tabs>

### Connection details

To set up the connection, provide the following details when creating the connector:

| Field               | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| **Service Account** | Paste the full JSON content of your service account key file |

***

## BigQuery actions

Once connected, you can use BigQuery in your workflows with the following actions:

### Insert

Insert new records into a BigQuery table.

**Configuration**

| Field        | Description                                      |
| ------------ | ------------------------------------------------ |
| **Dataset**  | The BigQuery dataset containing the target table |
| **Table**    | The table to insert data into                    |
| **Mappings** | Map columns to values using expressions          |

**Use cases**

* **Lead capture** – Insert new leads from form submissions or enrichment workflows
* **Event logging** – Record workflow events and outcomes
* **Data aggregation** – Store computed results for reporting

### Update

Update existing records in a BigQuery table based on a matching column.

**Configuration**

| Field               | Description                                      |
| ------------------- | ------------------------------------------------ |
| **Dataset**         | The BigQuery dataset containing the target table |
| **Table**           | The table to update                              |
| **Matching Column** | The column to match records against              |
| **Matching Value**  | The value to match (supports expressions)        |
| **Mappings**        | Map columns to new values using expressions      |

**Use cases**

* **Data enrichment** – Update records with enriched data from external sources
* **Status updates** – Mark records as processed or update stages
* **Sync external changes** – Keep BigQuery in sync with CRM or other systems

### Upsert

Create new records or update existing ones based on a matching column.

**Configuration**

| Field               | Description                                      |
| ------------------- | ------------------------------------------------ |
| **Dataset**         | The BigQuery dataset containing the target table |
| **Table**           | The table to upsert into                         |
| **Matching Column** | The column to match records against              |
| **Matching Value**  | The value to match (supports expressions)        |
| **Mappings**        | Map columns to values using expressions          |

**Use cases**

* **Data sync** – Keep your warehouse updated regardless of whether records exist
* **Idempotent operations** – Safely retry operations without creating duplicates
* **Master data management** – Maintain a single source of truth

### Delete

Delete records from a BigQuery table based on a matching column.

**Configuration**

| Field               | Description                                      |
| ------------------- | ------------------------------------------------ |
| **Dataset**         | The BigQuery dataset containing the target table |
| **Table**           | The table to delete from                         |
| **Matching Column** | The column to match records against              |
| **Matching Value**  | The value to match (supports expressions)        |

**Use cases**

* **Data cleanup** – Remove outdated or invalid records
* **GDPR compliance** – Delete personal data on request
* **Workflow automation** – Remove processed records from staging tables

***

## BigQuery data models

Cargo allows you to create data models on top of your BigQuery data that can be used to trigger Plays and power workflows.

### Creating BigQuery data models

To create a BigQuery data model:

1. Navigate to **Data Models** in Cargo
2. Click **Create data model**
3. Select **BigQuery** as the source
4. Configure the following fields:

| Field             | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| **Name**          | Choose a descriptive name for your model                    |
| **Slug**          | Set a unique identifier that cannot be changed once created |
| **Dataset**       | Select the BigQuery dataset containing your data            |
| **Table**         | Select the table or view to model                           |
| **ID Column**     | The column containing unique record identifiers             |
| **Title Column**  | The column to display as the record title                   |
| **Cursor Column** | (Optional) Column for incremental syncing (date or number)  |

### Using BigQuery data models

Once created, your BigQuery data model can be used to:

* **Trigger Plays** – Start automated workflows when data changes
* **Power enrichment** – Use BigQuery data to enrich records in workflows
* **Create segments** – Filter and target specific records from your data

***

## Required permissions

Ensure your service account has the following IAM roles:

<AccordionGroup>
  <Accordion title="Required IAM roles">
    * **BigQuery Data Editor** – Read and write data in BigQuery tables
    * **BigQuery Job User** – Run queries and jobs
    * **BigQuery Data Viewer** – (Optional) Read access to additional datasets outside your main dataset
  </Accordion>
</AccordionGroup>

### Required permissions breakdown

| Permission                   | Purpose                  |
| ---------------------------- | ------------------------ |
| `bigquery.tables.create`     | Create new tables        |
| `bigquery.tables.getData`    | Read data from tables    |
| `bigquery.tables.updateData` | Write data to tables     |
| `bigquery.jobs.create`       | Execute queries and jobs |

***

## Network configuration

If you restrict access to your BigQuery instance, add these Cargo IP addresses to your VPC firewall rules:

* `3.251.34.134`
* `54.220.135.99`
* `79.125.105.52`

***

## Security

* All BigQuery connections use Google's secure authentication
* Service account keys are encrypted at rest
* Data in transit is encrypted using TLS
* Cargo never overwrites existing tables—it always creates its own


# BounceBan
Source: https://docs.getcargo.ai/integration/bounceban

Connect BounceBan to verify email addresses, including accept-all and SEG-protected ones, in your workflows.

BounceBan verifies every kind of email address and specialises in the ones other
providers give up on: accept-all (catch-all) domains and mailboxes sitting behind
a Secure Email Gateway. Instead of returning those as risky, BounceBan tries to
establish whether they are actually deliverable.

## How to set up BounceBan

### Authentication

BounceBan uses API key authentication:

1. Sign up at [bounceban.com](https://bounceban.com)
2. Go to [your API settings](https://bounceban.com/app/api/settings)
3. Copy your API key
4. Paste the API key in Cargo when connecting

## BounceBan actions

### Verify email

Check whether an email address is deliverable.

**Required fields:**

* **Email**: The email address to verify

**Optional fields:**

* **Mode**: `regular` (default) or `deepverify`. DeepVerify assumes the email's
  domain is the owner's current company website — for example when the email and
  the company both come from the same LinkedIn profile — which raises the success
  rate on accept-all addresses.

**Credits:** 0.1 credits per verification

**Use case:** Validate emails before adding them to a sequence, and recover the
accept-all addresses a stricter verifier would have discarded.

## Verification results

Every verified email gets a `result` and a `score` from 0 to 100.

| Result        | Description                               |
| ------------- | ----------------------------------------- |
| deliverable   | Safe to send                              |
| risky         | May bounce — use the score to decide      |
| undeliverable | Will bounce, do not send                  |
| unknown       | Verification could not determine a result |

## Response data

| Field           | Description                             |
| --------------- | --------------------------------------- |
| email           | The verified email address              |
| result          | Verification result                     |
| score           | Deliverability confidence from 0 to 100 |
| is\_accept\_all | Does the domain accept every address?   |
| is\_disposable  | Is it a throwaway address?              |
| is\_role        | Is it a role address such as `sales@`?  |
| is\_free        | Is it a free provider such as Gmail?    |
| mx\_records     | MX records found for the domain         |
| smtp\_provider  | Email service provider, e.g. `Google`   |
| verify\_at      | When the verification completed         |

## How the result comes back

Most addresses are verified straight away and the node finishes on the spot. The
hard ones — accept-all domains, gateways that greylist the first connection —
take longer than BounceBan's synchronous window, so BounceBan keeps working in
the background and calls Cargo back once it has an answer. The node pauses in
the meantime and resumes on the callback, without occupying a worker.

Each email is submitted exactly once, so a verification is never billed twice.
If no callback arrives within 30 minutes, the node stops waiting and fails.

## Rate limits

BounceBan allows 100 verifications per second. Cargo handles rate limiting
automatically.

## Best practices

* Use DeepVerify when you know the email's domain is the person's current
  employer — it is what makes accept-all addresses resolvable
* Treat `risky` with the score rather than as a rejection: that band is where
  accept-all and gateway-protected addresses land
* Verify emails before importing them into your sending platform
* Re-verify older contacts periodically, since email addresses decay


# Bouncer
Source: https://docs.getcargo.ai/integration/bouncer

Connect Bouncer to verify email addresses with high accuracy in your workflows.

## How to set up Bouncer

### Authentication

Bouncer uses API key authentication:

1. Sign up at [usebouncer.com](https://usebouncer.com)
2. Navigate to **API** settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## Bouncer actions

### Verify email

Validate an email address and check deliverability.

**Required fields:**

* **Email**: The email address to verify

**Credits:** 0.3 credits per verification

## Verification results

Bouncer provides detailed verification statuses:

| Status        | Description                       |
| ------------- | --------------------------------- |
| deliverable   | Email exists and accepts messages |
| undeliverable | Email doesn't exist or bounces    |
| risky         | May bounce - use with caution     |
| unknown       | Couldn't determine status         |

## Response data

Bouncer returns comprehensive verification details:

| Field          | Description                    |
| -------------- | ------------------------------ |
| status         | Overall verification status    |
| reason         | Detailed reason for status     |
| email          | Verified email address         |
| domain         | Email domain                   |
| account        | Email account/username         |
| did\_you\_mean | Suggested typo correction      |
| role           | Is it a role-based email?      |
| free           | Is it a free email provider?   |
| disposable     | Is it a disposable email?      |
| accept\_all    | Does domain accept all emails? |

## Best practices

* Verify at point of capture for immediate feedback
* Re-verify before major campaigns
* Treat "risky" emails with caution - monitor for bounces
* Never email "undeliverable" addresses
* Use disposable email detection to filter low-quality leads
* Leverage "did\_you\_mean" for typo corrections
* Consider role-based emails carefully (info@, support@)

## Why use Bouncer?

* **High accuracy**: Advanced verification technology
* **Fast results**: Real-time verification
* **Detailed insights**: Rich metadata about each email
* **Typo detection**: Automatic correction suggestions
* **Disposable detection**: Identify throwaway emails
* **Role detection**: Identify generic addresses


# Bright Data
Source: https://docs.getcargo.ai/integration/bright-data

Connect Bright Data to scrape social media profiles and posts in your workflows.

## How to set up Bright Data

### Authentication

Bright Data uses API token authentication:

1. Sign up at [brightdata.com](https://brightdata.com)
2. Copy your API token from your account settings at [brightdata.com/cp/setting/users](https://brightdata.com/cp/setting/users)
3. Paste the API token in Cargo when connecting

Bright Data is also compatible with Cargo credits: if you don't connect your own account, actions run on Cargo's managed Bright Data access and are billed in Cargo credits.

<Note>
  **Code slugs** — integration slug: `brightData`. Actions: `scrapeInstagramProfile`, `scrapeTikTokProfile`, `scrapeFacebookPagePosts`, `scrapeFacebookProfile`, `scrapeTwitterProfile`, `scrapeYouTubeChannel`. Call them as `integrations.brightData.<action>(...)`.
</Note>

Cargo spreads requests at up to 100 calls per minute. Scrapes run asynchronously: Cargo polls the Bright Data snapshot until it completes.

## Bright Data actions

Every action takes a single required field and costs 0.1 Cargo credits per request when running on Cargo credits.

### Scrape Instagram profile

Scrape Instagram profile data by URL including follower count, posts, bio, and engagement metrics.

**Required fields:**

* **URL**: The URL of the Instagram profile to scrape

**Use case:** Qualify creators or brands by audience size and engagement before outreach.

### Scrape TikTok profile

Scrape TikTok profile data by URL including follower count, likes, videos, and engagement metrics.

**Required fields:**

* **URL**: The URL of the TikTok profile to scrape

**Use case:** Vet TikTok creators for influencer campaigns.

### Scrape Facebook page posts

Scrape Facebook page posts by URL including content, engagement metrics, and attachments.

**Required fields:**

* **URL**: The URL of the Facebook page to scrape posts from

**Use case:** Monitor a company's Facebook activity as a buying or engagement signal.

### Scrape Facebook profile

Scrape Facebook page or profile data by URL including name, followers, contact info, and business details.

**Required fields:**

* **URL**: The URL of the Facebook page or profile to scrape

**Use case:** Enrich local businesses with contact details (emails, websites, address) from their Facebook page.

### Scrape X (Twitter) profile

Scrape X (Twitter) profile data by URL including follower count, posts, bio, and engagement metrics.

**Required fields:**

* **URL**: The URL of the X (Twitter) profile to scrape

**Use case:** Score prospects by social reach and recent posting activity.

### Scrape YouTube channel

Scrape YouTube channel data by URL including subscriber count, videos, views, and top videos.

**Required fields:**

* **URL**: The URL of the YouTube channel to scrape

**Use case:** Identify high-reach channels for sponsorship or partnership outreach.

## Best practices

* Pass full profile/page URLs — each action targets one specific platform's dataset
* Scrapes can take a while to complete; runs stay in an executing state while Bright Data prepares the snapshot
* Results are cacheable in Cargo — avoid re-scraping the same URL in tight loops
* Use your own API token if you already have a Bright Data account; otherwise run on Cargo credits


# Calendly
Source: https://docs.getcargo.ai/integration/calendly

This page outlines how to use the Calendly integration to track scheduling events in Cargo.

Calendly is a scheduling automation platform that helps teams book meetings without the back-and-forth. Cargo's native integration with Calendly allows you to capture booking events and trigger automated workflows based on scheduling activities.

## How to set up Calendly

Calendly uses OAuth to establish the connection with Cargo. During connection, you'll be redirected to Calendly to authorize Cargo.

Once the connector is created, you can:

* **Set up Calendly data models** — Create data models from Calendly events to trigger Plays based on booking activities.
* **Track scheduling events** — Monitor when meetings are booked, canceled, or marked as no-shows.

***

## Calendly data models

Cargo allows you to create data models on top of your Calendly events that can be used to trigger Plays and power workflows.

### Creating Calendly data models

When creating a Calendly data model, configure which events to track:

| Event Type                  | Description                           |
| --------------------------- | ------------------------------------- |
| **Invitee created**         | A new meeting was booked              |
| **Invitee canceled**        | A meeting was canceled by the invitee |
| **Invitee no show created** | An invitee was marked as a no-show    |
| **Invitee no show deleted** | A no-show status was removed          |

<Tip>
  You can select multiple event types to track. Each event type will create
  records in your data model as they occur.
</Tip>

### Event data

Each Calendly event includes:

* **Invitee details** – Name, email, and any custom questions answered
* **Event details** – Event type, duration, and scheduled time
* **Scheduling info** – When the booking was made and by whom
* **Status** – Current status of the meeting

***

## Best practices

### Event selection

Choose which events to track based on your workflow needs:

* **Sales teams** – Track all events to monitor pipeline activity
* **Customer success** – Focus on cancellations and no-shows for churn prevention
* **Marketing** – Track new bookings to measure campaign effectiveness

### Data enrichment

Calendly events contain basic invitee information. Enhance your workflows by:

1. Looking up the invitee in your CRM for existing context
2. Enriching the invitee's company using domain enrichment
3. Scoring the meeting based on invitee attributes

### Response time

Calendly events are delivered in real-time. Take advantage of this for:

* Instant Slack notifications for high-priority bookings
* Immediate CRM updates to keep your team informed
* Same-day personalized confirmation emails


# Captain Data
Source: https://docs.getcargo.ai/integration/captain-data

Connect Captain Data to run automation workflows and scraping jobs in your pipelines.

## How to set up Captain Data

### Authentication

Captain Data requires API credentials:

1. Log in to your Captain Data account
2. Navigate to **Settings** → **API**
3. Obtain your credentials:
   * **API Key**
   * **Project UID**
4. Enter both in Cargo when connecting

## Captain Data actions

### Create job

Launch a Captain Data workflow with custom inputs.

**Required fields:**

* **Workflow**: Select the workflow to run

**Configuration:**

* **Inputs**: Map values to workflow input fields
* **Steps**: Configure accounts and parameters for each workflow step

**Use cases:**

* Trigger scraping jobs from Cargo workflows
* Run data extraction pipelines
* Execute multi-step automation workflows

### Cancel job

Stop a running Captain Data job.

**Required fields:**

* **UID**: The job UID to cancel

**Use case:** Cancel jobs that are no longer needed or taking too long.

### Retry job

Retry a failed Captain Data job.

**Required fields:**

* **UID**: The job UID to retry

**Use case:** Recover from transient failures without recreating the job.

### Find job

Get the status and results of a Captain Data job.

**Required fields:**

* **UID**: The job UID to retrieve

**Use case:** Check job completion status and retrieve results.

## Captain Data data models

### Fetch workflow results

Pull completed workflow results into Cargo.

**Required fields:**

* **Workflow**: Select the workflow to fetch results from
* **ID Column**: Define the unique identifier column

**Optional:**

* **Load jobs with warning**: Include results with warnings (default: no)

**Features:**

* Incremental sync
* 30-minute minimum sync interval
* Automatic retry on failures

## Best practices

* Use workflow presets for consistent configurations
* Monitor job status for large batch operations
* Configure appropriate accounts for each workflow step
* Use incremental fetch for workflow results
* Handle job failures with retry logic


# Cargo
Source: https://docs.getcargo.ai/integration/cargo

Source, match, enrich, and monitor businesses and prospects with Cargo's native B2B data.

Cargo ships with a built-in **Cargo** data connector — a managed B2B dataset of companies and people you can use directly inside any workflow. Use it to source target lists, match inbound records against firmographic data, enrich businesses and prospects across 13+ dimensions (firmographics, technographics, financials, hiring trends, intent, and more), and listen in real time for buying signals like funding rounds, role changes, or new product launches.

<Info>
  Because the Cargo connector is built into the platform, there is **nothing to
  authenticate** — usage is metered in [Cargo
  credits](/reference/credits).
</Info>

## How to set up Cargo

The Cargo connector is available in every workspace by default. To use it:

<Steps>
  <Step title="Add the connector">
    Open **Settings → Integrations**, click **Add connection**, and select
    **Cargo**. No API key is required.
  </Step>

  <Step title="Use it in a workflow">
    Choose **Cargo** from the node catalog inside a **Play**, **Tool**, or
    **Agent**, then pick one of the actions or extractors below.
  </Step>
</Steps>

<Tip>
  Cargo actions are credit-metered (see the [credits
  overview](/reference/credits)). Caching is enabled, so re-running
  an action on the same input will not consume additional credits.
</Tip>

***

## Concepts

The Cargo dataset is organised around two core entities, each identified by a stable ID returned by the matching/sourcing actions:

| Entity       | ID            | What it represents                                                                 |
| ------------ | ------------- | ---------------------------------------------------------------------------------- |
| **Business** | `business_id` | A company record (domain, firmographics, technographics, hiring, intent, events…). |
| **Prospect** | `prospect_id` | A person record (LinkedIn profile, role, contact info, career events…).            |

The typical flow is:

1. **Match** an inbound record (domain, email, LinkedIn URL, name) → get a `business_id` or `prospect_id`.
2. **Enrich** that ID with one or more enrichment actions to pull in firmographics, technographics, funding, intent, etc.
3. **Listen** for events on the matched record to trigger Plays when something changes.

Alternatively, use **Fetch** actions and extractors to **source** new businesses or prospects from scratch based on ICP filters.

***

## Sourcing actions

Use these actions to discover new accounts and contacts that match your ICP.

### Fetch businesses

Search the Cargo dataset for companies that match a set of ICP filters and return up to 100 matches. Useful inside Plays or Agents that need to dynamically pull a working list.

**Configuration**

| Field                                  | Description                                              |
| -------------------------------------- | -------------------------------------------------------- |
| **Country code**                       | Filter by country (e.g. `US`, `GB`, `FR`)                |
| **Region country code**                | Filter by region + country (e.g. `CA-US`)                |
| **City region country**                | Filter by city, region, country                          |
| **Company size**                       | Headcount band (`1-10`, `11-50`, …, `10001+`)            |
| **Company revenue**                    | Revenue band (`0-500K`, `500K-1M`, …, `10T+`)            |
| **Company age**                        | Years in business (`0-3`, `3-6`, `6-10`, `10-20`, `20+`) |
| **Number of locations**                | Physical location count                                  |
| **Google / NAICS / LinkedIn category** | Industry classifications                                 |
| **Company tech stack tech / category** | Specific technologies or stack categories                |
| **Website keywords**                   | Keywords found on the company website                    |
| **Company name**                       | Filter by name                                           |
| **Limit**                              | Records to return (1–100, default 25)                    |

<Tip>
  For larger sourcing jobs that should feed a **Model**, use the [Fetch
  businesses extractor](#fetch-businesses-extractor) instead — it paginates
  through up to 60,000 records.
</Tip>

### Fetch prospects

Search the Cargo dataset for people matching a set of ICP filters and return up to 100 prospects.

**Configuration**

| Field                                  | Description                                              |
| -------------------------------------- | -------------------------------------------------------- |
| **Business ID**                        | Restrict to prospects at specific companies              |
| **Job level**                          | Seniority (`C-Level`, `VP`, `Director`, …)               |
| **Job department**                     | Department (Engineering, Sales, Marketing, …)            |
| **Job title**                          | Free-form title filter                                   |
| **Country / region / city**            | Prospect location filters                                |
| **Company country / region**           | Company location filters                                 |
| **Company size / revenue**             | Firmographic filters on the prospect's company           |
| **Company name**                       | Filter by company name                                   |
| **Google / NAICS / LinkedIn category** | Industry filters on the prospect's company               |
| **Total experience months**            | Range filter (`gte` / `lte`) for total career experience |
| **Current role months**                | Range filter for tenure in current role                  |
| **Has email**                          | Only prospects with a known email                        |
| **Has phone number**                   | Only prospects with a known phone number                 |
| **Limit**                              | Records to return (1–100, default 25)                    |

### Fetch business statistics

Return aggregate counts (total companies, by size, by industry, by tech stack, etc.) for any combination of the same firmographic filters used in **Fetch businesses**. Useful to size a market before sourcing.

***

## Matching actions

Use matching actions to resolve external records into Cargo IDs so you can chain enrichment actions.

### Match business

Find a `business_id` from a company name and/or domain.

**Configuration**

| Field      | Description                                            |
| ---------- | ------------------------------------------------------ |
| **Name**   | Company name to match (optional if domain is provided) |
| **Domain** | Company domain/website (optional if name is provided)  |

Returns `✅ Match` with the matched business object, or `❌ No match` when no record was found.

### Match prospect

Find a `prospect_id` from any combination of identifiers.

**Configuration**

| Field            | Description                     |
| ---------------- | ------------------------------- |
| **Email**        | Prospect's email                |
| **Phone number** | Prospect's phone number         |
| **Full name**    | Prospect's full name            |
| **Company name** | Helps disambiguate common names |
| **LinkedIn URL** | Prospect's LinkedIn profile URL |

<Tip>
  Provide as many identifiers as you have — match accuracy increases with more
  signals. LinkedIn URL is the strongest single signal.
</Tip>

***

## Business enrichment actions

All business enrichment actions take a `business_id` (from [Match business](#match-business) or [Fetch businesses](#fetch-businesses)) and return the corresponding enrichment payload.

| Action                                       | What it returns                                           |
| -------------------------------------------- | --------------------------------------------------------- |
| **Enrich business firmographics**            | Headcount, revenue, location, industry codes, description |
| **Enrich business technographics**           | Technologies in the company's stack, by category          |
| **Enrich business financial metrics**        | Public financial metrics (revenue, growth, etc.)          |
| **Enrich business funding and acquisitions** | Funding rounds, investors, M\&A history                   |
| **Enrich business workforce trends**         | Hiring/attrition signals by department                    |
| **Enrich business ratings by employees**     | Glassdoor-style employee sentiment                        |
| **Enrich business strategic insights**       | AI-generated company strategy summary                     |
| **Enrich business challenges**               | Top business challenges and pain points                   |
| **Enrich business competitive landscape**    | Competitors and category positioning                      |
| **Enrich business LinkedIn posts**           | Recent posts from the company page                        |
| **Enrich business website keywords**         | Keywords / SEO terms ranked on the company site           |
| **Enrich business website changes**          | Recent changes detected on the company website            |
| **Enrich business Bombora intent topics**    | Bombora B2B research intent surge data                    |

**Enrich business Bombora intent topics** also accepts:

| Field             | Description                                                                     |
| ----------------- | ------------------------------------------------------------------------------- |
| **Intent topics** | List of `category: topic` filters. Include ≥ 12 topics for meaningful coverage. |
| **Minimum score** | Minimum composite intent score threshold (must be > 60, default 60).            |

***

## Prospect enrichment actions

All prospect enrichment actions take a `prospect_id` (from [Match prospect](#match-prospect) or [Fetch prospects](#fetch-prospects)).

| Action                               | What it returns                                              |
| ------------------------------------ | ------------------------------------------------------------ |
| **Enrich prospect details**          | Contact info (emails, phone numbers) for the prospect        |
| **Enrich prospect LinkedIn profile** | Structured LinkedIn profile (experience, education, skills…) |
| **Enrich prospect LinkedIn posts**   | Recent posts and reactions from the prospect's profile       |

***

## Event actions

Pull historical signals on demand for a single business or prospect.

### Fetch business events

Return business events that happened on or after a given timestamp.

**Configuration**

| Field              | Description                                                                     |
| ------------------ | ------------------------------------------------------------------------------- |
| **Business ID**    | The business to fetch events for                                                |
| **Event types**    | One or more event types (see [Business event types](#business-event-types))     |
| **Timestamp from** | ISO 8601 timestamp — only events from this date onwards are returned (optional) |

### Fetch prospect events

Same as above, scoped to a prospect.

**Configuration**

| Field              | Description                                                                           |
| ------------------ | ------------------------------------------------------------------------------------- |
| **Prospect ID**    | The prospect to fetch events for                                                      |
| **Event types**    | `prospect_changed_role`, `prospect_changed_company`, `prospect_job_start_anniversary` |
| **Timestamp from** | ISO 8601 timestamp (optional)                                                         |

***

## Extractors

Extractors sync data from Cargo into a **Model**, where it can power Plays, segments, and CRM syncs. They come in two flavours:

* **Fetch** extractors run paginated, on-demand pulls of records that match a filter.
* **Listen** extractors enroll a set of records and stream **new events** into the model in real time.

### Fetch businesses extractor

Bulk-pulls businesses into a Model using the same ICP filters as the [Fetch businesses](#fetch-businesses) action, but paginates up to **60,000 records** per run (page size 500).

The output model is keyed on `business_id` and exposes the following columns:

`business_id`, `name`, `domain`, `logo`, `country_name`, `city_name`, `number_of_employees_range`, `yearly_revenue_range`, `website`, `business_description`, `region`, `naics`, `naics_description`, `sic_code`, `sic_code_description`, `business_intent_topics`, `events`, `linkedin_profile`.

### Fetch prospects extractor

Same pattern as **Fetch businesses extractor**, applied to prospects.

### Listen business events

Enroll a set of businesses (sourced from a Model column of LinkedIn company URLs or domains) and **continuously ingest** business events into Cargo as they happen. Each new event becomes a record in the destination Model and is unified onto the matching account.

**Configuration**

| Field                             | Description                                                          |
| --------------------------------- | -------------------------------------------------------------------- |
| **Event types**                   | One or more [business event types](#business-event-types) to monitor |
| **Model**                         | Model that contains the businesses to enroll                         |
| **LinkedIn URL or domain column** | Column on the model containing LinkedIn company URLs or domains      |
| **Filter / Sort**                 | Optional model filter/sort to narrow which records get enrolled      |
| **Limit**                         | Max businesses to enroll (default 1,000, max 10,000)                 |

Each ingested event is materialised as a row with `event_id`, `event_name`, `event_time`, `business_id`, `domain`, `linkedin_company_url`, and an `event_data` object containing the structured event payload.

<Info>
  Listen extractors auto-ingest in the background. Update the Model filter or
  the column slug at any time — the enrolled set is reconciled automatically.
</Info>

### Listen prospect events

Same pattern, scoped to prospects. Enroll a set of prospects from a Model column of LinkedIn profile URLs and stream `prospect_changed_role`, `prospect_changed_company`, and `prospect_job_start_anniversary` events into a Model in real time.

***

## Reference

### Business event types

The following event types are available for **Fetch business events** and **Listen business events**:

**Funding & corporate**

* `ipo_announcement`
* `new_funding_round`
* `new_investment`
* `new_product`
* `new_office`
* `closing_office`
* `new_partnership`

**Department growth / contraction**

* `increase_in_engineering_department` (and similar for `sales`, `marketing`, `operations`, `customer_service`, `all_departments`)
* `decrease_in_engineering_department` (and similar for the same departments)

**Hiring signals**

* `employee_joined_company`
* `hiring_in_engineering_department` (and similar for `creative`, `education`, `finance`, `health`, `human_resources`, `legal`, `marketing`, `operations`, `professional_service`, `sales`, `support`, `trade`, `unknown` departments)

### Prospect event types

* `prospect_changed_role`
* `prospect_changed_company`
* `prospect_job_start_anniversary`

***

## Use cases

<AccordionGroup>
  <Accordion title="ICP sourcing" icon="bullseye">
    Use the **Fetch businesses extractor** with firmographic + technographic
    filters to build a working list, then enrich each row with firmographics,
    technographics, and intent data to score against your ICP.
  </Accordion>

  <Accordion title="Inbound lead enrichment" icon="inbox">
    On every new lead, **Match business** on the email domain to get a
    `business_id`, then chain **Enrich business firmographics** and **Enrich
    business funding and acquisitions** to push enriched fields into your CRM.
  </Accordion>

  <Accordion title="Job change tracking" icon="user-tag">
    Enroll your CRM contacts into **Listen prospect events** with event type
    `prospect_changed_role` or `prospect_changed_company` to surface job-change
    signals into a Play that pings the new account.
  </Accordion>

  <Accordion title="Funding signals" icon="sack-dollar">
    Enroll target accounts into **Listen business events** with `new_funding_round`
    and `new_investment` to trigger outreach the moment a target raises capital.
  </Accordion>

  <Accordion title="Hiring intent" icon="user-plus">
    Use **Listen business events** with `hiring_in_*` event types to detect
    accounts ramping up specific teams — a strong signal for tooling sales.
  </Accordion>

  <Accordion title="Intent-based outreach" icon="signal-stream">
    Combine **Enrich business Bombora intent topics** with the **Bombora**
    intent surge dataset to prioritise accounts actively researching your
    category.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Match before you enrich.** Every enrichment action requires a `business_id` or `prospect_id`. Cache the match output on the model so subsequent enrichment runs are free.
2. **Batch with extractors.** Use the Fetch *extractors* (not the Fetch *actions*) when you need more than 100 records — they paginate to 60,000.
3. **Pick the right event surface.** Use **Fetch business/prospect events** for ad-hoc lookups; use **Listen business/prospect events** when you want a Play to react to new signals automatically.
4. **Be specific with intent topics.** Bombora intent works best when you supply 12+ topics in the same category — fewer than that produces noisy scores.
5. **Caching is on by default.** Identical inputs (same `business_id`, same filter set) won't be re-billed within the caching window — design your workflows to lean on idempotent inputs.


# Clearbit
Source: https://docs.getcargo.ai/integration/clearbit

This page outlines how to use the Clearbit integration for data enrichment in Cargo.

Clearbit provides real-time business intelligence APIs that help companies enrich their data with information about people and companies. Cargo's native integration with Clearbit allows you to enrich contacts and companies directly from your workflows.

## How to set up Clearbit

To connect Clearbit, you'll need an API key from your Clearbit account.

### Connection details

| Field       | Description           |
| ----------- | --------------------- |
| **API Key** | Your Clearbit API key |

<Tip>Find your API key in Clearbit under **API → API Keys**.</Tip>

Once the connector is created, you can:

* **Use Clearbit in workflows** — Choose **Clearbit** from the node catalog within a **Play**, **Tool**, or **Agent**.

***

## Clearbit actions

### Enrich Person

Retrieve detailed information about a person using their email address.

**Use cases**

* **Lead enrichment** – Enrich inbound leads with professional details
* **Contact scoring** – Use enriched data for lead scoring
* **Personalization** – Gather context for personalized outreach

**Configuration**

| Field     | Description                 |
| --------- | --------------------------- |
| **Email** | Email address of the person |

**Additional fields** (optional)

| Field              | Description                        |
| ------------------ | ---------------------------------- |
| **Given name**     | First name of the person           |
| **Family name**    | Last name of the person            |
| **IP address**     | IP address for location enrichment |
| **Location**       | Geographic location                |
| **Company**        | Company name                       |
| **Company domain** | Company domain                     |
| **LinkedIn**       | LinkedIn profile URL               |
| **Twitter**        | Twitter handle or URL              |
| **Facebook**       | Facebook profile URL               |

<Info>Providing additional fields improves match accuracy when email alone isn't enough.</Info>

### Enrich Company

Retrieve detailed information about a company using their domain.

**Use cases**

* **Account enrichment** – Enrich target accounts with firmographic data
* **ICP scoring** – Score companies against your ideal customer profile
* **Market research** – Gather company intelligence

**Configuration**

| Field      | Description                        |
| ---------- | ---------------------------------- |
| **Domain** | Company domain (e.g., company.com) |

**Additional fields** (optional)

| Field            | Description                   |
| ---------------- | ----------------------------- |
| **Company name** | Name of the company           |
| **LinkedIn**     | Company LinkedIn page URL     |
| **Twitter**      | Company Twitter handle or URL |
| **Facebook**     | Company Facebook page URL     |


# ClearoutPhone
Source: https://docs.getcargo.ai/integration/clearout-phone

Validate phone numbers with ClearoutPhone

ClearoutPhone is a phone number validation service that verifies phone numbers for accuracy and deliverability.

## Authentication

Connect to ClearoutPhone using your API key.

### Connection details

| Field       | Description                |
| ----------- | -------------------------- |
| **API key** | Your ClearoutPhone API key |

***

## ClearoutPhone actions

### Verify phone

Validate a phone number to check if it's valid and reachable.

**Configuration**

| Field            | Description                              |
| ---------------- | ---------------------------------------- |
| **Phone number** | The phone number to validate             |
| **Country code** | ISO 3166 Alpha-2 country code (optional) |

**Returns**

| Field     | Description                  |
| --------- | ---------------------------- |
| Validity  | Whether the number is valid  |
| Line type | Mobile, landline, VoIP, etc. |
| Carrier   | Phone carrier information    |
| Location  | Geographic location data     |

***

## Use cases

<AccordionGroup>
  <Accordion title="Lead validation" icon="phone">
    Validate phone numbers at point of capture.
  </Accordion>

  <Accordion title="Data cleaning" icon="broom">
    Clean phone number lists before outreach campaigns.
  </Accordion>

  <Accordion title="SMS campaign prep" icon="message">
    Ensure phone numbers are valid before SMS campaigns.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Include country code** - Provide the country code for more accurate validation
2. **Validate before calling** - Verify numbers before adding to dialer campaigns
3. **Check line type** - Filter by line type based on your outreach strategy


# Cleon1
Source: https://docs.getcargo.ai/integration/cleon1

Connect Cleon1 to find direct phone numbers in your workflows.

## How to set up Cleon1

### Authentication

Cleon1 uses API key authentication:

1. Sign up at [cleon1.com](https://cleon1.com)
2. Copy your API key from your Cleon1 dashboard
3. Paste the API key in Cargo when connecting

Cleon1 is also compatible with Cargo credits: if you don't connect your own account, actions run on Cargo's managed Cleon1 access.

<Note>
  **Code slugs** — integration slug: `cleon1`. Actions: `findPhoneFromLinkedin`, `findPhone`. Call them as `integrations.cleon1.<action>(...)`.
</Note>

Cargo spreads requests at up to 10 calls per second against the Cleon1 API.

## Cleon1 actions

### Find phone from LinkedIn

Find a person's direct phone number from their LinkedIn profile URL.

**Required fields:**

* `linkedinUrl`: The person's LinkedIn profile URL

Returns the direct phone number along with the person's name, company name, company domain, LinkedIn URL, and your remaining Cleon1 credits.

**Use case:** Get direct dials for prospects you already have LinkedIn profiles for.

### Find phone

Find a person's direct phone number from their name and company.

**Required fields:**

* `firstName`: Person's first name
* `lastName`: Person's last name

**Optional fields:**

* `companyName`: Name of the company the person works at
* `companyDomain`: Domain of the company

**Use case:** Look up phone numbers when you have a name and company but no LinkedIn URL.

## Best practices

* Prefer **Find phone from LinkedIn** when a LinkedIn URL is available — it's the most reliable identifier
* Add a company name or domain to name-based lookups to improve matching
* Results are cacheable in Cargo — avoid redundant lookups for the same person


# Close
Source: https://docs.getcargo.ai/integration/closecom

This page outlines how to use the Close integration to manage your sales CRM in Cargo.

Close is a sales CRM built for high-velocity sales teams, featuring built-in calling, email, and automation. Cargo's native integration with Close allows you to manage leads, contacts, and activities directly from your workflows.

## How to set up Close

Close uses OAuth to establish the connection with Cargo. During connection, you'll be redirected to Close to authorize Cargo.

Once the connector is created, you can:

* **Set up Close data models** — Create data models from your Close leads, contacts, and activities to trigger Plays.
* **Use Close in workflows** — Choose **Close** from the node catalog within a **Play**, **Tool**, or **Agent**.

***

## Close actions

<Tip>
  Close actions support Leads and Contacts, with full support for custom fields
  on both object types.
</Tip>

### Insert lead

Create a new lead in Close.

**Use cases**

* **Lead capture** – Create leads from inbound sources
* **Data sync** – Push leads from other systems
* **Pipeline building** – Add qualified prospects

**Configuration**

| Field               | Description              |
| ------------------- | ------------------------ |
| **Mappings**        | Map standard lead fields |
| **Custom mappings** | Map custom field values  |

### Insert contact

Create a new contact associated with a lead.

**Use cases**

* **Contact creation** – Add contacts to existing leads
* **Multi-contact leads** – Build out account contacts

**Configuration**

| Field                  | Description                   |
| ---------------------- | ----------------------------- |
| **Associated lead ID** | The lead to attach contact to |
| **Email address**      | Contact's email               |
| **Phone number**       | Contact's phone               |
| **Mappings**           | Map standard contact fields   |
| **Custom mappings**    | Map custom field values       |

### Update leads

Update existing lead records.

**Configuration**

| Field                      | Description                 |
| -------------------------- | --------------------------- |
| **Matching Property Name** | Field to match on           |
| **Matching Value**         | Value to match against      |
| **Mappings**               | Map fields to update        |
| **Custom mappings**        | Map custom fields to update |

### Update contacts

Update existing contact records.

**Configuration**

| Field                      | Description                 |
| -------------------------- | --------------------------- |
| **Matching Property Name** | Field to match on           |
| **Matching Value**         | Value to match against      |
| **Mappings**               | Map fields to update        |
| **Custom mappings**        | Map custom fields to update |

### Upsert leads

Create new leads or update existing ones.

**Configuration**

| Field                      | Description             |
| -------------------------- | ----------------------- |
| **Matching Property Name** | Field to match on       |
| **Matching Value**         | Value to match against  |
| **Mappings**               | Map lead fields         |
| **Custom mappings**        | Map custom field values |

### Upsert contacts

Create new contacts or update existing ones.

**Configuration**

| Field                      | Description               |
| -------------------------- | ------------------------- |
| **Matching Property Name** | Field to match on         |
| **Matching Value**         | Value to match against    |
| **Associated lead ID**     | Lead to attach contact to |
| **Email address**          | Contact's email           |
| **Phone number**           | Contact's phone           |
| **Mappings**               | Map contact fields        |
| **Custom mappings**        | Map custom field values   |

### Search leads

Retrieve leads matching filter criteria.

**Configuration**

| Field      | Description               |
| ---------- | ------------------------- |
| **Filter** | Define filter conditions  |
| **Sort**   | Sort results              |
| **Limit**  | Maximum records to return |

### Search contacts

Retrieve contacts matching filter criteria.

**Configuration**

| Field      | Description               |
| ---------- | ------------------------- |
| **Filter** | Define filter conditions  |
| **Sort**   | Sort results              |
| **Limit**  | Maximum records to return |

### Delete leads

Delete leads matching specified criteria.

### Delete contacts

Delete contacts matching specified criteria.

***

## Close data models

Create data models from Close to trigger automated workflows.

### Available extractors

<AccordionGroup>
  <Accordion title="Fetch leads" icon="building">
    Pull lead records with incremental sync.
  </Accordion>

  <Accordion title="Fetch contacts" icon="user">
    Pull contact records with incremental sync.
  </Accordion>

  <Accordion title="Fetch opportunities" icon="handshake">
    Pull opportunity records.
  </Accordion>

  <Accordion title="Fetch tasks" icon="check">
    Pull task records.
  </Accordion>

  <Accordion title="Activity extractors" icon="chart-line">
    Pull various activity types: - Lead created activities - Call activities -
    Email activities - Email thread activities - Meeting activities - Note
    activities - SMS activities - Task completed activities - Lead status change
    activities - Opportunity status change activities
  </Accordion>
</AccordionGroup>


# Cognism
Source: https://docs.getcargo.ai/integration/cognism

Access premium B2B contact data with Cognism

Cognism is a B2B sales intelligence platform providing verified contact and company data. The Cargo integration enables you to enrich records and search for accounts and contacts.

## Authentication

Connect to Cognism using your API key.

### Connection details

| Field       | Description          |
| ----------- | -------------------- |
| **API Key** | Your Cognism API key |

***

## Cognism actions

### Enrich account

Retrieve detailed company information.

**Configuration**

Provide company identifiers such as domain, name, or other matching criteria to retrieve comprehensive account data.

### Enrich contact

Retrieve verified contact information including emails and phone numbers.

**Configuration**

Provide contact identifiers such as name, email, LinkedIn URL, or company information to retrieve verified contact data.

### Search accounts

Search for companies matching specific criteria.

**Configuration**

Define search filters based on company attributes like industry, size, location, and technology stack.

### Search contacts

Search for contacts matching specific criteria.

**Configuration**

Define search filters based on contact attributes like job title, seniority, department, and company information.

***

## Use cases

<AccordionGroup>
  <Accordion title="Contact enrichment" icon="user-plus">
    Enrich leads with verified mobile numbers and email addresses.
  </Accordion>

  <Accordion title="Account research" icon="building">
    Get comprehensive company profiles with firmographic data.
  </Accordion>

  <Accordion title="Prospecting" icon="magnifying-glass">
    Build targeted prospect lists based on ICP criteria.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use multiple identifiers** - Provide multiple data points for better match rates
2. **Verify before outreach** - Use Cognism's verified data for higher deliverability
3. **Combine with intent** - Layer Cognism data with intent signals for prioritization


# Company Enrich
Source: https://docs.getcargo.ai/integration/company-enrich

Enrich companies and find similar companies with Company Enrich

Company Enrich is a B2B data platform that provides company enrichment and lookalike company discovery.

## Authentication

Connect to Company Enrich using your API key.

### Connection details

| Field       | Description                 |
| ----------- | --------------------------- |
| **API Key** | Your Company Enrich API key |

***

## Company Enrich actions

### Enrich by domain

Retrieve detailed company information from a domain name.

**Configuration**

| Field      | Description                        |
| ---------- | ---------------------------------- |
| **Domain** | Company domain (e.g., company.com) |

**Returns**

Comprehensive company data including firmographics, technographics, and social profiles.

### Find similar companies

Discover companies matching specific criteria.

**Configuration**

| Filter Category | Available Filters                       |
| --------------- | --------------------------------------- |
| **Industry**    | Filter by industries                    |
| **Technology**  | Filter by technologies used             |
| **Keywords**    | Filter by business keywords             |
| **Location**    | Region, country, state, city            |
| **Size**        | Employee count min/max                  |
| **Revenue**     | Revenue range (USD)                     |
| **Founded**     | Year founded range                      |
| **Limit**       | Maximum results (default: 10, max: 100) |

***

## Use cases

<AccordionGroup>
  <Accordion title="Account enrichment" icon="building">
    Enrich CRM accounts with comprehensive company data.
  </Accordion>

  <Accordion title="Lookalike targeting" icon="clone">
    Find companies similar to your best customers.
  </Accordion>

  <Accordion title="Technology targeting" icon="microchip">
    Identify companies using specific technologies.
  </Accordion>

  <Accordion title="Market expansion" icon="map">
    Discover companies in new geographic markets.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Start with domain enrichment** - Get baseline data before searching for similar companies
2. **Combine multiple filters** - Use industry + technology + location for targeted lists
3. **Use technology filters** - Great for competitive displacement campaigns
4. **Cache results** - Results are cached to reduce costs on repeated lookups


# ContactOut
Source: https://docs.getcargo.ai/integration/contact-out

Connect ContactOut to find contact information and search for people and companies in your workflows.

## How to set up ContactOut

### Authentication

ContactOut uses API key authentication:

1. Sign up at [contactout.com](https://contactout.com)
2. Navigate to your API settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## ContactOut actions

### Enrich

Find contact or company data from LinkedIn URL or company domain.

**For contacts:**

* **LinkedIn URL**: Person's LinkedIn profile URL (required)
* **Include phone**: Add phone data to response
* **Email type**: Personal, Work, or both

**For companies:**

* **Company domain**: Company's domain (required)

**Credits:**

| Configuration            | Credits |
| ------------------------ | ------- |
| Company enrichment       | 0       |
| Contact (no email/phone) | 1       |
| Contact with email       | 2       |
| Contact with phone       | 3       |

### Search

Search for people or companies using various filters.

**For people, filter by:**

* Skills
* Education
* Location
* Company / Domain
* Job title
* Industry
* Company size
* Years of experience
* Years in current role

**For companies, filter by:**

* Name
* Domain
* Location
* Size
* Industries
* Revenue range
* Year founded

**Data type options:**

* Personal email
* Work email
* Phone

**Reveal info:** Set to true to get contact information (charges credits)

**Credits:**

* Search without reveal: 1 credit per result
* Search with reveal: 3 credits per result

## Response data

### Contact enrichment returns:

| Field    | Description              |
| -------- | ------------------------ |
| name     | Full name                |
| title    | Job title                |
| company  | Company name             |
| emails   | Array of email addresses |
| phones   | Array of phone numbers   |
| linkedin | LinkedIn profile URL     |
| location | Geographic location      |

### Company enrichment returns:

| Field    | Description             |
| -------- | ----------------------- |
| name     | Company name            |
| domain   | Company domain          |
| industry | Industry classification |
| size     | Employee count          |
| revenue  | Revenue range           |
| location | Headquarters location   |

## Best practices

* Use company enrichment (free) for account research
* Select only the email types you need to optimize credits
* Use search filters to find precise prospects
* Enable reveal only when you need contact info
* Cache results to avoid duplicate lookups
* Combine with CRM sync for lead management


# Contrast
Source: https://docs.getcargo.ai/integration/contrast

Track video engagement and registrations with Contrast

Contrast is a video hosting and analytics platform for B2B marketing. The Cargo integration enables you to track video views, registrations, and create registrations programmatically.

## Authentication

Connect to Contrast using your API key.

### Connection details

| Field       | Description           |
| ----------- | --------------------- |
| **API Key** | Your Contrast API key |

***

## Contrast actions

### Search registrations

Retrieve video registrations with filtering options.

**Configuration**

| Field          | Description              |
| -------------- | ------------------------ |
| **Video slug** | Filter by specific video |
| **User email** | Filter by viewer email   |
| **Start date** | Start of date range      |
| **End date**   | End of date range        |
| **Limit**      | Maximum results          |

### Search views

Retrieve video view data with filtering options.

**Configuration**

| Field          | Description              |
| -------------- | ------------------------ |
| **Video slug** | Filter by specific video |
| **User email** | Filter by viewer email   |
| **Start date** | Start of date range      |
| **End date**   | End of date range        |
| **Limit**      | Maximum results          |

### Search events

Retrieve channel events with filtering options.

**Configuration**

| Field            | Description         |
| ---------------- | ------------------- |
| **Channel slug** | Filter by channel   |
| **Start date**   | Start of date range |
| **End date**     | End of date range   |
| **Limit**        | Maximum results     |

### Create registration

Create a video registration for a viewer.

**Configuration**

| Field          | Description                      |
| -------------- | -------------------------------- |
| **Email**      | Viewer's email (required)        |
| **First name** | Viewer's first name              |
| **Last name**  | Viewer's last name               |
| **Video slug** | Video to register for (required) |

***

## Use cases

<AccordionGroup>
  <Accordion title="Lead scoring" icon="star">
    Boost lead scores based on video engagement.
  </Accordion>

  <Accordion title="Sales alerts" icon="bell">
    Notify sales when prospects watch specific videos.
  </Accordion>

  <Accordion title="Automated registration" icon="user-plus">
    Register leads for video content programmatically.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Track high-intent videos** - Focus on demo or pricing video views
2. **Use email filters** - Track specific accounts' video engagement
3. **Combine with CRM data** - Match video viewers to CRM records


# Coresignal
Source: https://docs.getcargo.ai/integration/coresignal

Access B2B company, member, and job data from Coresignal

Coresignal provides fresh B2B data including company profiles, professional member data, and job postings. The Cargo integration enables you to search and retrieve data across all three object types.

## Authentication

Connect to Coresignal using your API key.

### Connection details

| Field       | Description             |
| ----------- | ----------------------- |
| **API Key** | Your Coresignal API key |

***

## Coresignal actions

### Search members

Search for professional members (contacts) based on various criteria.

**Configuration**

| Filter Category | Available Filters                                          |
| --------------- | ---------------------------------------------------------- |
| **Member**      | Name, title, location, summary, skills, industry, country  |
| **Experience**  | Company name, title, industry, size, employee count, dates |
| **Education**   | Institution name, program, description, dates              |
| **Refresh**     | Created date, last updated date                            |
| **Limit**       | Maximum records to retrieve (max: 25)                      |

### Search companies

Search for companies based on firmographic criteria.

**Configuration**

| Filter Category | Available Filters                                                |
| --------------- | ---------------------------------------------------------------- |
| **Company**     | Name, website, location, industry, size, country, employee count |
| **Funding**     | Last round type, total rounds count, last round date             |
| **Refresh**     | Created date, last updated date                                  |
| **Limit**       | Maximum records to retrieve (max: 25)                            |

### Search jobs

Search for job postings across companies.

**Configuration**

| Filter Category | Available Filters                                             |
| --------------- | ------------------------------------------------------------- |
| **Job**         | Title, keywords, location, country, industry, employment type |
| **Company**     | Company ID, name, domain, website, LinkedIn URL               |
| **Refresh**     | Created date, last updated date                               |
| **Limit**       | Maximum records to retrieve (max: 25)                         |

***

## Use cases

<AccordionGroup>
  <Accordion title="Prospecting" icon="magnifying-glass">
    Find contacts at target companies based on title, skills, and experience.
  </Accordion>

  <Accordion title="Hiring signals" icon="briefcase">
    Track job postings to identify companies in growth mode or with specific needs.
  </Accordion>

  <Accordion title="Company research" icon="building">
    Research companies by funding stage, size, and industry.
  </Accordion>

  <Accordion title="Talent mapping" icon="users">
    Analyze employee movements and career transitions.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use specific filters** - Combine multiple filters for more targeted results
2. **Track job postings** - Job data provides valuable buying signals
3. **Monitor funding rounds** - Companies with recent funding are often expanding


# CSV
Source: https://docs.getcargo.ai/integration/csv

Upload CSV files to import records into your Cargo data models.

## How to set up CSV

### Authentication

The CSV integration requires no authentication:

1. Search for the CSV integration in the settings panel or the node catalog
2. Create the connector by giving it a name and slug — no credentials are needed

<Note>
  **Code slugs** — integration slug: `csv`. This integration has no actions; it provides one extractor, `upload`, used when creating or syncing a model from a file.
</Note>

## Data models

The CSV integration is a data source, not an action provider: it exposes an **Upload** extractor that imports the rows of a CSV file as records into a Cargo data model.

When configuring an upload:

* **File**: The CSV file to import (CSV only, max 2GB)
* **ID**: The column used to deduplicate records
* **Mappings** (optional): Map file columns to the column names of your model; if you use mappings, the ID column must be included in them

Cargo previews the first rows of the file so you can validate the mapping before running the full import. Uploads are one-shot fetches — re-upload a file to refresh the data.

## Best practices

* Pick a genuinely unique column (email, external ID) as the ID to avoid collapsing distinct records during deduplication
* Use mappings to normalize messy header names into clean model column slugs
* Keep files under the 2GB limit; split very large exports into multiple uploads
* Re-run the upload extractor with a fresh file to update the model — imports are not incremental


# Custom Integration
Source: https://docs.getcargo.ai/integration/custom-integration

Build your own custom integration to connect any external service with Cargo.

Custom integrations allow you to extend Cargo's capabilities by connecting to any external service or API. By building a custom integration server, you can create actions, data extractors, and autocomplete endpoints that seamlessly integrate with Cargo's workflows.

<Info>
  Check out the [dummy-integration
  repository](https://github.com/getcargohq/dummy-integration) for a complete
  working example of a custom integration.
</Info>

***

## Overview

A custom integration is an HTTP server that implements a specific API contract. Cargo communicates with your integration server to:

* **Fetch the manifest** — Describes your integration's capabilities (actions, extractors, autocompletes)
* **Authenticate connections** — Validates user credentials when creating a connector
* **Execute actions** — Performs operations in your external service
* **Fetch data** — Pulls data from your service into Cargo data models
* **Provide autocomplete options** — Powers dynamic dropdowns in the Cargo UI

***

## Getting started

A custom integration can be hosted in two ways:

* **As a Cargo Hosting worker** *(recommended)* — write the integration as an edge `fetch(request, env)` handler and let Cargo host it. No infra, no ngrok, no separate domain.
* **As an externally hosted server** — a Node/Express (or any language) server you host yourself. Use this when you need a runtime that isn't supported by workers, or you already have an existing server to wrap.

### Option A — Build with a Cargo Worker (recommended)

#### Step 1: Scaffold the worker

```bash theme={null}
npx @cargo-ai/cli hosting worker init my-integration --template custom-integration
cd my-integration
npm install
```

This drops a TypeScript worker (typed against [`@cargo-ai/worker-sdk`](https://www.npmjs.com/package/@cargo-ai/worker-sdk)) that already implements the Custom Integration HTTP contract:

```
my-integration/
├── manifest.json               # kind + outboundAllowlist (hosts the worker may call)
├── package.json
├── tsconfig.json
└── src/
    ├── index.ts                # default { fetch(request, env) } — routes the contract
    ├── getManifest.ts          # GET /manifest
    ├── authenticate.ts         # POST /authenticate
    ├── listUsers.ts            # POST /listUsers
    ├── completeOauth.ts        # POST /completeOauth
    ├── actions/                # POST /actions/<slug>/execute
    ├── extractors/             # POST /extractors/<slug>/{fetch,count}
    ├── autocompletes/          # POST /autocompletes/<slug>
    └── dynamicSchemas/         # POST /dynamicSchemas/<slug>
```

Edit `src/getManifest.ts` (manifest), `src/authenticate.ts` (credential check), and the per-action / per-extractor handlers under `src/`. Add any external hosts you call to `manifest.json#outboundAllowlist`. Run `npm run type:check` to validate against the typed contract.

#### Step 2: Provision a worker slot, deploy, promote

```bash theme={null}
# Returns <workerUuid>
cargo-ai hosting worker create --name "My Integration" --slug my-integration

# Returns <deploymentUuid>. Deploy the source directory — no local build step.
cargo-ai hosting deployment create --worker-uuid <workerUuid> --source ./

cargo-ai hosting deployment promote --uuid <deploymentUuid>
```

The Cargo Hosting build pipeline runs `npm ci` + `esbuild src/index.ts --bundle --format=esm --platform=neutral --target=es2022` (esbuild transpiles TypeScript natively) to produce the final edge bundle.

#### Step 3: Register the worker as a custom integration

```bash theme={null}
cargo-ai connection custom-integration create \
  --kind worker \
  --worker-uuid <workerUuid>
```

Or declaratively in a project:

```ts theme={null}
import { defineCustomIntegration, defineWorker } from "@cargo-ai/cdk";

const worker = defineWorker("my-integration", {
  path: new URL("./my-integration", import.meta.url).pathname,
});

export const integration = defineCustomIntegration("my-integration", {
  worker,
});
```

Cargo will fetch `GET /manifest` from your worker (cached for 5 minutes) and the integration will appear in your workspace's connector catalog.

<Tip>
  Use `cargo-ai hosting worker init x --list-templates` to see all available
  worker templates.
</Tip>

### Option B — Self-hosted external server

Use this path when you can't run on a worker (long-running compute, large native dependencies, an existing Express/Flask/Go service you want to expose, etc.).

#### Step 1: Create your integration server

Start by cloning the dummy integration repository:

```bash theme={null}
git clone https://github.com/getcargohq/dummy-integration.git
cd dummy-integration
npm install
```

Run the development server:

```bash theme={null}
npm run dev
```

Your integration server will start on a local port (e.g., `http://localhost:3000`).

#### Step 2: Expose your local server with ngrok

During development, you can use [ngrok](https://ngrok.com/) to expose your local server to the internet:

```bash theme={null}
ngrok http 3000
```

This will give you a public URL like `https://abc123.ngrok.io` that you can use to register your integration with Cargo.

<Tip>
  For production, deploy your integration server to a cloud provider (AWS, GCP,
  Vercel, Railway, etc.) and use that URL instead.
</Tip>

#### Step 3: Register the external server in Cargo

```bash theme={null}
cargo-ai connection custom-integration create \
  --kind external \
  --base-url https://abc123.ngrok.io
```

Or via raw HTTP:

```bash theme={null}
curl -X POST https://api.getcargo.io/v1/connection/customIntegrations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "external",
    "baseUrl": "https://abc123.ngrok.io"
  }'
```

Once registered, Cargo will fetch the manifest from your server and the integration will appear in your workspace's connector catalog.

<Warning>
  Your external integration server must be publicly accessible. Cargo's backend
  needs to make HTTP requests to your server's endpoints.
</Warning>

***

## Cargo API for custom integrations

Manage your custom integrations using these API endpoints. All endpoints require authentication.

### Create a custom integration

```
POST /v1/connection/customIntegrations
```

**Request body** — discriminated by `kind`:

```json theme={null}
// Externally hosted server
{
  "kind": "external",
  "baseUrl": "https://your-integration-server.com"
}
```

```json theme={null}
// Cargo Hosting worker-backed
{
  "kind": "worker",
  "workerUuid": "11111111-2222-3333-4444-555555555555"
}
```

**Response:**

```json theme={null}
{
  "customIntegration": {
    "uuid": "ci_abc123",
    "kind": "external",
    "baseUrl": "https://your-integration-server.com",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}
```

### List custom integrations

```
GET /v1/connection/customIntegrations/list
```

**Response:**

```json theme={null}
{
  "customIntegrations": [
    {
      "uuid": "ci_abc123",
      "kind": "external",
      "baseUrl": "https://your-integration-server.com",
      "createdAt": "2025-01-01T00:00:00Z"
    },
    {
      "uuid": "ci_def456",
      "kind": "worker",
      "workerUuid": "11111111-2222-3333-4444-555555555555",
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ]
}
```

### Get a custom integration

```
GET /v1/connection/customIntegrations/:uuid
```

**Response:**

```json theme={null}
{
  "connector": {
    "uuid": "ci_abc123",
    "kind": "external",
    "baseUrl": "https://your-integration-server.com",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}
```

### Update a custom integration

```
PUT /v1/connection/customIntegrations/:uuid
```

**Request body** — pass either `baseUrl` (for `external` integrations) or `workerUuid` (for `worker` integrations); the integration's `kind` cannot change.

```json theme={null}
{
  "baseUrl": "https://new-integration-server.com"
}
```

### Delete a custom integration

```
DELETE /v1/connection/customIntegrations/:uuid
```

***

## Integration server API

Your integration server must implement the following HTTP endpoints:

### GET /manifest

Returns the integration manifest describing all capabilities.

**Response:**

```json theme={null}
{
  "name": "My Integration",
  "description": "A custom integration for my service",
  "icon": "<svg>...</svg>",
  "color": "#6366F1",
  "url": "https://myservice.com",
  "connector": {
    "config": {
      "jsonSchema": {
        "type": "object",
        "properties": {
          "apiKey": {
            "title": "API Key",
            "type": "string"
          }
        },
        "required": ["apiKey"]
      },
      "uiSchema": {}
    },
    "rateLimit": {
      "unit": "minute",
      "max": 60
    }
  },
  "actions": {
    "createRecord": {
      "name": "Create Record",
      "description": "Creates a new record in the service",
      "config": {
        "jsonSchema": {
          "type": "object",
          "properties": {
            "name": {
              "title": "Name",
              "type": "string"
            }
          },
          "required": ["name"]
        },
        "uiSchema": {}
      }
    }
  },
  "extractors": {
    "fetchRecords": {
      "name": "Fetch Records",
      "description": "Fetches records from the service",
      "config": {
        "jsonSchema": {},
        "uiSchema": {}
      },
      "mode": {
        "kind": "fetch",
        "isIncremental": false
      },
      "preview": "records"
    }
  },
  "autocompletes": {
    "listOptions": {
      "params": {
        "jsonSchema": {}
      },
      "cacheExpirationInSeconds": 300
    }
  }
}
```

***

### POST /authenticate

Validates the connector configuration (credentials).

**Request body:**

```json theme={null}
{
  "connectorConfig": {
    "apiKey": "encrypted_value"
  }
}
```

**Response (success):**

```json theme={null}
{
  "outcome": "success"
}
```

**Response (error):**

```json theme={null}
{
  "outcome": "error",
  "reason": "unauthenticated",
  "errorMessage": "Invalid API key provided"
}
```

***

### POST /listUsers

Lists users available in the connected service (optional).

**Request body:**

```json theme={null}
{
  "connectorConfig": {
    "apiKey": "encrypted_value"
  }
}
```

**Response:**

```json theme={null}
[
  {
    "id": "user_123",
    "email": "john@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "profileImage": "https://example.com/avatar.png"
  }
]
```

***

### POST /actions/\[actionSlug]/execute

Executes an action. The `actionSlug` corresponds to a key in the `actions` object returned by your `/manifest` endpoint.

**Request body:**

```json theme={null}
{
  "connectorConfig": {
    "apiKey": "encrypted_value"
  },
  "actionConfig": {
    "name": "New Record Name"
  }
}
```

**Response (completed):**

```json theme={null}
{
  "outcome": "executed",
  "title": "Record created successfully",
  "data": {
    "id": "rec_123",
    "name": "New Record Name",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}
```

**Response (in progress):**

```json theme={null}
{
  "outcome": "executing"
}
```

***

### POST /extractors/\[extractorSlug]/fetch

Fetches data for a data model extractor.

**Request body:**

```json theme={null}
{
  "connectorConfig": {
    "apiKey": "encrypted_value"
  },
  "extractorConfig": {},
  "meta": {}
}
```

**Response:**

```json theme={null}
{
  "outcome": "fetched",
  "columns": [
    {
      "slug": "id",
      "type": "string",
      "label": "ID"
    },
    {
      "slug": "name",
      "type": "string",
      "label": "Name"
    },
    {
      "slug": "createdAt",
      "type": "date",
      "label": "Created At"
    }
  ],
  "idColumnSlug": "id",
  "titleColumnSlug": "name",
  "uniqueColumns": [],
  "data": {
    "kind": "records",
    "records": [
      {
        "action": "upsert",
        "override": true,
        "record": {
          "id": "rec_123",
          "name": "Record 1",
          "createdAt": "2025-01-01T00:00:00Z"
        }
      }
    ],
    "hasMore": false
  }
}
```

***

### POST /extractors/\[extractor]/count

Returns the count of records for preview purposes.

**Response:**

```json theme={null}
{
  "count": 150
}
```

***

### POST /autocompletes/\[autocompleteSlug]

Provides options for dynamic dropdowns in the UI.

**Request body:**

```json theme={null}
{
  "connectorConfig": {
    "apiKey": "encrypted_value"
  },
  "params": {}
}
```

**Response:**

```json theme={null}
{
  "results": [
    {
      "label": "Option 1",
      "value": "option_1",
      "description": "Description for option 1"
    },
    {
      "label": "Option 2",
      "value": "option_2"
    }
  ]
}
```

***

### POST /dynamicSchemas/\[schemaSlug]

Returns dynamic JSON schemas based on runtime parameters.

**Request body:**

```json theme={null}
{
  "connectorConfig": {
    "apiKey": "encrypted_value"
  },
  "params": {}
}
```

**Response:**

```json theme={null}
{
  "jsonSchema": {
    "type": "object",
    "properties": {
      "dynamicField": {
        "title": "Dynamic Field",
        "type": "string"
      }
    }
  },
  "uiSchema": {}
}
```

***

### POST /completeOauth

Completes OAuth flow for integrations using OAuth authentication.

**Request body:**

```json theme={null}
{
  "code": "oauth_authorization_code",
  "redirectUri": "https://app.getcargo.io/oauth/callback"
}
```

**Response:**

```json theme={null}
{
  "value": "encrypted_oauth_token"
}
```

***

## Using autocompletes in action/extractor forms

To power dynamic dropdowns in your action configuration forms, use the `IntegrationAutocompleteWidget` in your `uiSchema`. This widget calls your `/autocompletes/{slug}` endpoint to fetch options.

### Basic usage

In your `/manifest` endpoint response, include an `autocompletes` entry and reference it in an action's `uiSchema`:

```json theme={null}
{
  "autocompletes": {
    "listWorkspaces": {
      "params": {
        "jsonSchema": {}
      },
      "cacheExpirationInSeconds": 300
    }
  },
  "actions": {
    "syncData": {
      "name": "Sync Data",
      "description": "Sync data from a workspace",
      "config": {
        "jsonSchema": {
          "type": "object",
          "properties": {
            "workspaceId": {
              "type": "string",
              "title": "Workspace"
            }
          },
          "required": ["workspaceId"]
        },
        "uiSchema": {
          "workspaceId": {
            "ui:widget": "IntegrationAutocompleteWidget",
            "ui:options": {
              "slug": "listWorkspaces",
              "params": {}
            }
          }
        }
      }
    }
  }
}
```

### Widget options

| Option         | Type    | Description                                                   |
| -------------- | ------- | ------------------------------------------------------------- |
| `slug`         | string  | The autocomplete slug (matches entry in `/manifest` response) |
| `params`       | object  | Static or dynamic parameters to pass to the endpoint          |
| `allowRefresh` | boolean | Show a refresh button to reload options                       |

### Dynamic parameters

You can reference other form values in `params` using special path expressions:

```json theme={null}
{
  "uiSchema": {
    "accounts": {
      "ui:widget": "IntegrationAutocompleteWidget",
      "ui:options": {
        "slug": "listAccounts",
        "params": {
          "workspaceId": "$this.$parent.workspaceId"
        }
      }
    }
  }
}
```

**Path expressions:**

| Expression | Description                         |
| ---------- | ----------------------------------- |
| `$this`    | Current field value                 |
| `$parent`  | Parent object in the form structure |
| `$root`    | Root of the form data               |

This allows cascading dropdowns where one field's options depend on another field's selected value.

***

## Using dynamic schemas

For fields where the schema depends on runtime values (like user selections), use the `DynamicSchemaWidget`. This widget fetches the JSON schema from your `/dynamicSchemas/{slug}` endpoint.

### Basic usage

In your `/manifest` endpoint response, include a `dynamicSchemas` entry and reference it in an action's `uiSchema`:

```json theme={null}
{
  "dynamicSchemas": {
    "getFieldSchema": {
      "params": {
        "jsonSchema": {
          "type": "object",
          "properties": {
            "objectType": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "actions": {
    "createRecord": {
      "name": "Create Record",
      "description": "Create a record with dynamic fields",
      "config": {
        "jsonSchema": {
          "type": "object",
          "properties": {
            "objectType": {
              "type": "string",
              "title": "Object Type"
            },
            "fields": {
              "type": "object",
              "title": "Fields"
            }
          }
        },
        "uiSchema": {
          "objectType": {
            "ui:widget": "IntegrationAutocompleteWidget",
            "ui:options": {
              "slug": "listObjectTypes"
            }
          },
          "fields": {
            "ui:widget": "DynamicSchemaWidget",
            "ui:options": {
              "slug": "getFieldSchema",
              "params": {
                "objectType": "$this.$parent.objectType"
              }
            }
          }
        }
      }
    }
  }
}
```

### Widget options

| Option   | Type   | Description                                                     |
| -------- | ------ | --------------------------------------------------------------- |
| `slug`   | string | The dynamic schema slug (matches entry in `/manifest` response) |
| `params` | object | Parameters to pass to the endpoint (supports path expressions)  |

### Endpoint response

Your `/dynamicSchemas/{slug}` endpoint should return both the JSON schema and UI schema for the field:

```json theme={null}
{
  "jsonSchema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "title": "Name"
      },
      "email": {
        "type": "string",
        "title": "Email"
      }
    }
  },
  "uiSchema": {}
}
```

<Tip>
  Dynamic schemas are useful when your integration has different fields per
  object type (e.g., CRM objects like Contacts vs Companies) or when fields are
  user-configurable.
</Tip>

***

## Best practices

<CardGroup>
  <Card title="Validate inputs" icon="shield-check">
    Always validate connector and action configurations before processing
    requests.
  </Card>

  <Card title="Handle errors gracefully" icon="triangle-exclamation">
    Return meaningful error messages to help users troubleshoot issues.
  </Card>

  <Card title="Implement rate limiting" icon="gauge">
    Define rate limits in your `/manifest` response to prevent overwhelming your
    service.
  </Card>

  <Card title="Use caching" icon="database">
    Enable caching for autocomplete endpoints to improve performance.
  </Card>
</CardGroup>

***

## Example integration

For a complete working example, see the [Cargo Dummy Integration](https://github.com/getcargohq/dummy-integration) repository on GitHub.

The repository includes:

* Full project structure with TypeScript
* Example `/manifest` endpoint with actions and extractors
* Authentication endpoint implementation
* Action execution handlers
* Development and build scripts


# Customer.io
Source: https://docs.getcargo.ai/integration/customerio

Connect Customer.io to manage customer messaging, segments, and event tracking in your workflows.

## How to set up Customer.io

### Authentication

Customer.io requires multiple API credentials:

1. Log in to your Customer.io account

2. Navigate to **Settings** → **Account Settings** → **API Credentials**

3. You'll need:
   * **App Region**: Select US or EU based on where your data is stored
   * **App API Key**: For accessing the App API (manage segments, customers)
   * **Site ID**: Your Customer.io site identifier
   * **Site API Key**: For the Tracking API (send events, update customers)

4. Enter all credentials in Cargo when connecting

## Customer.io actions

### Upsert customer

Create a new customer or update an existing one in Customer.io.

**Required fields:**

* **Matching Value**: The value to identify the customer
* **Matching Field Name**: Choose how to match (External ID, Email, or CIO ID)

**Optional fields:**

* **Mappings**: Additional attributes to set on the customer profile

**Use cases:**

* Sync customer data from your CRM to Customer.io
* Update customer attributes when enrichment data is available
* Create customers when they sign up or convert

### Delete customer

Remove a customer from Customer.io.

**Required fields:**

* **Matching Value**: The value to identify the customer
* **Matching Field Name**: Choose how to match (External ID, Email, or CIO ID)

**Use case:** Remove customers who have been deleted from your system or requested data deletion.

### Add customer to segment

Add a customer to a manual segment in Customer.io.

**Required fields:**

* **Matching Value**: The value to identify the customer
* **Matching Field Name**: Choose how to match (External ID, Email, or CIO ID)
* **Segment**: Select the segment to add them to

**Use cases:**

* Add customers to a segment for a targeted campaign
* Segment customers based on external data or scores
* Build audiences for personalized messaging

### Remove customer from segment

Remove a customer from a manual segment.

**Required fields:**

* **Matching Value**: The value to identify the customer
* **Matching Field Name**: Choose how to match (External ID, Email, or CIO ID)
* **Segment**: Select the segment to remove them from

### Track event

Send a custom event for a customer.

**Required fields:**

* **Name**: Event name
* **Customer ID**: The customer identifier

**Optional fields:**

* **Mappings**: Event properties/attributes

**Use cases:**

* Track product usage events from your backend
* Send conversion events for campaign attribution
* Trigger automated campaigns based on custom events

### Track page

Record a page view for a customer.

**Required fields:**

* **Customer ID**: The customer identifier
* **Page URL**: The URL of the page viewed

## Best practices

* Use consistent customer identifiers across systems
* Include relevant attributes when upserting customers to power personalization
* Use descriptive event names that align with your Customer.io campaigns
* Leverage segments for campaign targeting rather than individual customer updates


# Datachimp
Source: https://docs.getcargo.ai/integration/datachimp

Track new hires and job offers with Datachimp

Datachimp is a B2B data platform that provides real-time signals on new hires and job postings. The Cargo integration enables you to receive these signals as triggers for your workflows.

## Authentication

Datachimp uses Cargo credits. No additional API key is required.

***

## Data models

### Fetch new hires

Track new hires at target companies based on job titles and company criteria.

**Configuration**

| Field                   | Description                      |
| ----------------------- | -------------------------------- |
| **Titles**              | Job titles to track (required)   |
| **Excluded titles**     | Job titles to exclude            |
| **Countries**           | Target countries (required)      |
| **Industries**          | Filter by industries             |
| **Excluded industries** | Industries to exclude            |
| **Company sizes**       | Filter by company size           |
| **Fundraising rounds**  | Filter by last fundraising round |
| **Limit**               | Maximum records per 30 days      |

### Fetch job offers

Track job postings matching your criteria.

**Configuration**

| Field                   | Description                              |
| ----------------------- | ---------------------------------------- |
| **Titles**              | Job titles to track (required)           |
| **Excluded titles**     | Job titles to exclude                    |
| **Job locations**       | Countries where jobs are located         |
| **Company locations**   | Company headquarters locations           |
| **Industries**          | Filter by industries                     |
| **Excluded industries** | Industries to exclude                    |
| **Exclude recruitment** | Remove staffing agency postings          |
| **Company sizes**       | Filter by company size                   |
| **Fundraising rounds**  | Filter by last fundraising round         |
| **Tools**               | Highlight specific tools in descriptions |
| **Filter by tools**     | Only return jobs mentioning tools        |
| **Limit**               | Maximum records per 30 days              |

***

## Credits

| Extractor        | Cost                 |
| ---------------- | -------------------- |
| Fetch new hires  | 2 credits per record |
| Fetch job offers | 2 credits per record |

***

## Use cases

<AccordionGroup>
  <Accordion title="Champion tracking" icon="user-check">
    Track when your champions move to new companies.
  </Accordion>

  <Accordion title="Hiring signals" icon="briefcase">
    Identify companies hiring for roles that signal buying intent.
  </Accordion>

  <Accordion title="Competitive intelligence" icon="eye">
    Monitor job postings mentioning competitor tools.
  </Accordion>

  <Accordion title="Territory expansion" icon="map">
    Find companies hiring in your target markets.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Be specific with titles** - Target specific job titles for better signal quality
2. **Use industry filters** - Focus on industries relevant to your ICP
3. **Monitor tools mentions** - Track job postings mentioning competitor products
4. **Exclude recruitment firms** - Filter out staffing agency noise


# Datagma
Source: https://docs.getcargo.ai/integration/datagma

Connect Datagma to find emails and phone numbers in your workflows.

## How to set up Datagma

### Authentication

Datagma uses API ID authentication:

1. Sign up at [datagma.com](https://datagma.com)
2. Navigate to your API settings
3. Copy your API ID
4. Paste the API ID in Cargo when connecting

## Datagma actions

### Enrich person

Enrich a person from an identifier you already have, rather than from their name
and company.

**Required fields:**

* **LinkedIn URL or email**: LinkedIn profile URL or professional email address

**Optional fields:**

* **Country code**: Two-letter country code, to avoid matching a namesake

Returns the person's profile alongside their emails and phone numbers.

**Credits:** 8 credits per request

**Use case:** Enrich contacts captured from LinkedIn, or complete a record you
only have an email address for.

### Enrich person from personal email

Retrieve a person's profile from a personal email address — the one they signed
up with, rather than their work address.

**Required fields:**

* **Email**: Personal email address

Only supported for people outside of the EU.

**Credits:** 2 credits per request

**Use case:** Identify freemail signups so they can be routed and enriched like
any other lead.

### Find email

Find a person's email address using their name and company.

**Required fields:**

* **First name**: Person's first name
* **Last name**: Person's last name
* **Company name**: Company name

**Credits:** 1 credit per request

**Use case:** Discover professional email addresses for prospecting.

### Find phone

Get a person's phone number using their email or LinkedIn URL.

**Input fields (provide at least one):**

* **Email**: Person's email address
* **Personal LinkedIn URL**: LinkedIn profile URL

**Credits:** 8 credits per request

**Use case:** Get direct phone numbers for high-priority contacts.

### Find phone and email

Retrieve both phone number and email address in one request.

**Required fields:**

* **First name**: Person's first name
* **Last name**: Person's last name
* **Company name**: Company name

**Credits:** 8 credits per request

**Use case:** Get complete contact data in a single lookup.

## Credits summary

| Action                            | Credits |
| --------------------------------- | ------- |
| Enrich person                     | 8       |
| Enrich person from personal email | 2       |
| Find email                        | 1       |
| Find phone                        | 8       |
| Find phone and email              | 8       |

**Tip:** Use "Find phone and email" when you need both - it costs the same as finding phone alone but gives you both data points.

## Best practices

* Use combined action when you need both email and phone
* Provide company name for better matching accuracy
* Use LinkedIn URL for phone lookups when available
* Cache results to avoid redundant credit usage
* Prioritize phone lookups for high-value prospects due to credit cost


# dbt
Source: https://docs.getcargo.ai/integration/dbt

Sync data from your dbt models into Cargo

dbt (data build tool) is the standard for data transformation in modern data stacks. The Cargo integration allows you to pull data from your dbt models directly into Cargo data models.

## Authentication

Connect to dbt Cloud using your API token and account details.

### Connection details

| Field           | Description              |
| --------------- | ------------------------ |
| **API Token**   | Your dbt Cloud API token |
| **Account**     | Your dbt account         |
| **Environment** | Your dbt environment     |

<Tip>
  Generate your API token in dbt Cloud under **Account Settings → API Access**.
</Tip>

***

## Data models

### Fetch model

Pull data from a dbt model into a Cargo data model.

**Configuration**

| Field     | Description                             |
| --------- | --------------------------------------- |
| **Model** | Select the dbt model to sync            |
| **ID**    | Column containing unique record IDs     |
| **Title** | Column containing record display titles |

<Info>
  Cargo dynamically loads available models and columns from your dbt environment.
</Info>

***

## Use cases

<AccordionGroup>
  <Accordion title="Transformed data sync" icon="arrows-rotate">
    Use dbt-transformed data as the source for your Cargo workflows.
  </Accordion>

  <Accordion title="Business metrics" icon="chart-line">
    Pull calculated metrics and aggregations from dbt models.
  </Accordion>

  <Accordion title="Data quality" icon="shield-check">
    Leverage dbt's tested and documented models for reliable data.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use production environment** - Connect to your production dbt environment for stable, tested data
2. **Set proper ID columns** - Choose columns that uniquely identify each record
3. **Document your models** - dbt model descriptions appear in Cargo's model selector


# DeepSeek
Source: https://docs.getcargo.ai/integration/deep-seek

Connect DeepSeek to use powerful AI models for text generation and reasoning in your workflows.

## How to set up DeepSeek

### Authentication

DeepSeek uses API key authentication:

1. Sign up at [deepseek.com](https://deepseek.com)
2. Navigate to API settings
3. Generate an API key
4. Copy the API key and paste it in Cargo when connecting

## DeepSeek actions

### Instruct

Generate text responses using DeepSeek's AI models.

**Required fields:**

* **Model**: Select the DeepSeek model
* **Prompt**: Your instruction or question

**Available models:**

| Model       | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| DeepSeek-V3 | General-purpose chat model for diverse tasks                |
| DeepSeek-R1 | Advanced reasoning model with chain-of-thought capabilities |

**Advanced settings:**

* **System prompt**: Set context for the model's behavior
* **Maximum tokens**: Limit response length (1-8192, default 4096)
* **Temperature**: Control randomness (0-2, default 1)

**Output options:**

* **Text**: Plain text response
* **JSON object**: Structured JSON output

## Use cases

* **Lead research**: Analyze and summarize information about prospects
* **Email writing**: Generate personalized sales outreach
* **Data transformation**: Convert data between formats
* **Question answering**: Build FAQ or support automation
* **Analysis**: Complex reasoning on business data

## Model comparison

| Feature  | DeepSeek-V3            | DeepSeek-R1            |
| -------- | ---------------------- | ---------------------- |
| Speed    | Faster                 | Slower                 |
| Best for | General tasks          | Complex reasoning      |
| Output   | Direct answers         | Step-by-step reasoning |
| Use when | Quick responses needed | Accuracy is critical   |

## Best practices

* Use DeepSeek-V3 for straightforward generation tasks
* Use DeepSeek-R1 when you need the model to "show its work"
* Lower temperature (0.2-0.5) for factual, consistent outputs
* Higher temperature (0.7-1.0) for creative content
* Use JSON object output for structured data extraction
* Provide clear, specific system prompts for best results

## Example prompts

**Lead qualification:**

```
Analyze this lead and determine if they match our ICP:
- Company: {{company_name}}
- Industry: {{industry}}
- Size: {{employee_count}}

Our ICP: B2B SaaS companies, 50-500 employees, in tech industry.

Respond with qualification status and reasoning.
```

**Email personalization:**

```
Write a cold email to {{first_name}} at {{company_name}}.
They are a {{job_title}} and their company {{recent_news}}.
Keep it under 100 words, casual tone, focus on {{value_prop}}.
```


# Devin
Source: https://docs.getcargo.ai/integration/devin

Launch Devin sessions to work on engineering tasks

Devin is an AI software engineer that works on tasks autonomously in its own environment. The Cargo integration lets a workflow launch a Devin session and use what it produced — structured output and pull requests — in downstream nodes.

## Authentication

Connect to Devin with a service user API key. Create a service user under **Settings → Service users**, give it a role with the `ManageOrgSessions` and `ViewOrgSessions` permissions, and generate a key. The key is only shown once.

### Connection details

| Field               | Description                                        |
| ------------------- | -------------------------------------------------- |
| **API Key**         | A Devin service user API key, starting with `cog_` |
| **Organization ID** | Your Devin organization ID, starting with `org-`   |

Both are on the **Settings → Service users** page. The organization ID is part of every
API path, so a wrong value fails the connection test the same way a wrong key does.

***

## Devin actions

### Launch agent

Create a Devin session and send it a task.

**Configuration**

| Field             | Description                                       |
| ----------------- | ------------------------------------------------- |
| **Prompt**        | The task Devin should work on                     |
| **Session title** | Title shown in the Devin session list             |
| **Playbook**      | A reusable procedure for Devin to follow          |
| **Repositories**  | Repositories to make available to the session     |
| **Devin mode**    | Normal, Fast, Lite, Ultra or Fusion               |
| **Max ACU limit** | Caps how many ACUs the session may consume        |
| **Tags**          | Tags applied to the session, useful for reporting |

The **Playbook** dropdown lists the organization and enterprise playbooks your service
user can see. Preview Devin modes have to be enabled for your organization; leave the
field empty to use the organization default.

**Output**

| Field       | Description                  |
| ----------- | ---------------------------- |
| `sessionId` | Session identifier           |
| `url`       | Link to the session in Devin |
| `status`    | Session status at creation   |
| `title`     | Session title                |

<Note>
  The node completes as soon as the session is created — it does not wait for Devin to
  finish. The Devin API has no callback to announce that a session finished, so there is
  nothing to wait on without polling.
</Note>

That means the output carries the session's identity rather than its results: structured
output, pull requests and ACUs consumed only exist once Devin has done some work, so they
would always be empty here. Follow the session at its `url`, or read it back from the
Devin API with the `sessionId`.

***

## Use cases

<AccordionGroup>
  <Accordion title="Automated code changes" icon="code-branch">
    Turn a qualified request into a pull request without a human in the loop.
  </Accordion>

  <Accordion title="Codebase research" icon="magnifying-glass">
    Ask Devin to investigate a repository and return structured findings.
  </Accordion>

  <Accordion title="Repeatable procedures" icon="book">
    Run a playbook per incoming item so every session follows the same steps.
  </Accordion>

  <Accordion title="Triage at scale" icon="list-check">
    Launch one session per incoming issue and collect the pull requests they open.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Give Devin a complete prompt** - Nothing downstream is waiting to answer a follow-up question
2. **Use playbooks for repeated work** - They keep sessions consistent across records
3. **Set a max ACU limit** - It bounds what a single run can cost
4. **Tag sessions launched from Cargo** - It makes them easy to find in reporting, and it is how you correlate a workflow run with the sessions it started


# Dropcontact
Source: https://docs.getcargo.ai/integration/dropcontact

Connect Dropcontact to find and verify professional email addresses in your workflows.

## How to set up Dropcontact

### Authentication

Dropcontact uses API key authentication:

1. Log in to your Dropcontact account
2. Navigate to **API** section
3. Copy your API key
4. Paste the API key in Cargo when connecting

## Dropcontact actions

### Find email

Find a person's professional email address using identifying information.

**Input fields (provide as many as available):**

* **Email**: Known email to validate/enrich
* **First name**: Person's first name
* **Last name**: Person's last name
* **Full name**: Full name (alternative to first/last)
* **Phone**: Phone number
* **Company**: Company name
* **Website**: Company website/domain
* **LinkedIn**: Person's LinkedIn profile URL
* **Company LinkedIn**: Company LinkedIn page URL
* **Country**: Country (helps with localization)
* **SIREN/SIRET**: French company identifiers (for French companies)

**Use cases:**

* Find email addresses for leads with name and company
* Enrich partial contact data
* Validate existing email addresses
* Complete profiles from LinkedIn data

## Response data

Dropcontact returns enriched contact information including:

| Field       | Description                 |
| ----------- | --------------------------- |
| email       | Professional email address  |
| first\_name | Cleaned first name          |
| last\_name  | Cleaned last name           |
| full\_name  | Complete name               |
| company     | Company name                |
| website     | Company domain              |
| linkedin    | LinkedIn profile URL        |
| phone       | Phone number (if available) |
| job         | Job title                   |
| seniority   | Seniority level             |

## Credits

Dropcontact uses a credit-based system:

* Each email lookup costs 1 credit
* Credits are tracked by Cargo

Caching is supported to avoid duplicate lookups for the same contact.

## Rate limits

Dropcontact API has a rate limit of 60 requests per minute. The integration includes automatic retry logic with exponential backoff for reliability.

## Best practices

* Provide as much identifying information as possible for higher match rates
* Use caching to optimize credit usage
* Combine with other enrichment sources for better coverage
* Company domain often yields better results than company name alone
* LinkedIn URL provides the most reliable matching


# Email Bison
Source: https://docs.getcargo.ai/integration/email-bison

Connect Email Bison to create and manage leads in your cold email campaigns.

## How to set up Email Bison

### Authentication

Email Bison uses API key authentication with a dedicated instance domain:

1. Log in to your Email Bison account
2. Copy your dedicated instance URL (e.g. `https://send.acme.com`) — this is different for each account
3. Generate an API token from your Email Bison settings
4. In Cargo, create an **Email Bison** connector
5. Paste your instance URL in the **Domain** field
6. Paste your API token in the **API key** field

## Email Bison actions

### Create lead

Create a new lead in Email Bison.

**Required fields:**

* **Email**: The lead's email address
* **First name**: The lead's first name
* **Last name**: The lead's last name

**Optional fields:**

* **Title**: The lead's job title
* **Company**: The lead's company name
* **Notes**: Additional notes about the lead
* **Custom variables**: Key-value pairs for personalization

### Update lead

Update an existing lead in Email Bison.

**Required fields:**

* **Lead ID**: The ID of the lead to update
* **Email**: The lead's email address
* **First name**: The lead's first name
* **Last name**: The lead's last name

**Optional fields:**

* **Title**: The lead's job title
* **Company**: The lead's company name
* **Notes**: Additional notes about the lead
* **Custom variables**: Key-value pairs for personalization

### Upsert lead

Create a lead if it doesn't exist, or update it if it does.

**Required fields:**

* **Email**: The lead's email address
* **First name**: The lead's first name
* **Last name**: The lead's last name

**Optional fields:**

* **Title**: The lead's job title
* **Company**: The lead's company name
* **Notes**: Additional notes about the lead
* **Custom variables**: Key-value pairs for personalization

**Use case:** Sync leads from your CRM or enrichment tools into Email Bison campaigns without worrying about duplicates.

## Rate limits

Email Bison is rate-limited to 10 requests per second. Cargo automatically handles rate limiting to ensure reliable delivery.


# EnrichCRM
Source: https://docs.getcargo.ai/integration/enrich-crm

Find emails and enrich contacts and companies with EnrichCRM

EnrichCRM is a data enrichment platform that provides email finding, contact enrichment, and company enrichment capabilities.

## Authentication

Connect to EnrichCRM using your API key.

### Connection details

| Field       | Description            |
| ----------- | ---------------------- |
| **API key** | Your EnrichCRM API key |

***

## EnrichCRM actions

### Find email

Find a person's email address using various identifiers.

**Configuration**

| Field                | Description                           |
| -------------------- | ------------------------------------- |
| **First name**       | Person's first name                   |
| **Last name**        | Person's last name                    |
| **Full name**        | Full name (alternative to first/last) |
| **Company**          | Domain (recommended) or company name  |
| **Company LinkedIn** | Company LinkedIn slug                 |
| **Country**          | Person's country                      |

### Enrich person

Retrieve detailed information about a contact.

**Configuration**

| Field          | Description                           |
| -------------- | ------------------------------------- |
| **Email**      | Person's email address                |
| **First name** | Person's first name                   |
| **Last name**  | Person's last name                    |
| **Full name**  | Full name (alternative to first/last) |
| **Domain**     | Company domain                        |

### Enrich company

Retrieve detailed company information.

**Configuration**

| Field            | Description                 |
| ---------------- | --------------------------- |
| **Domain**       | Company domain              |
| **Filmographic** | Include filmographic data   |
| **Tech**         | Include technology stack    |
| **Financial**    | Include financial data      |
| **French data**  | Include French company data |

***

## Credits

| Action         | Cost     |
| -------------- | -------- |
| Find email     | 1 credit |
| Enrich person  | 1 credit |
| Enrich company | 1 credit |

***

## Use cases

<AccordionGroup>
  <Accordion title="Email discovery" icon="envelope">
    Find verified emails for outreach campaigns.
  </Accordion>

  <Accordion title="Contact enrichment" icon="user-plus">
    Enrich leads with complete profile information.
  </Accordion>

  <Accordion title="Company research" icon="building">
    Get comprehensive company data including financials and tech stack.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use domain over company name** - Domain matching provides better accuracy
2. **Combine identifiers** - Provide multiple fields for better match rates
3. **Cache results** - Results are cached to reduce credit usage


# Enrichley
Source: https://docs.getcargo.ai/integration/enrichley

Verify email addresses with Enrichley

Enrichley is an email verification service that validates email addresses for deliverability.

## Authentication

Connect to Enrichley using your API key.

### Connection details

| Field       | Description            |
| ----------- | ---------------------- |
| **API key** | Your Enrichley API key |

***

## Enrichley actions

### Verify

Verify an email address to check if it's deliverable.

**Configuration**

| Field           | Description                  |
| --------------- | ---------------------------- |
| **Object type** | Type of verification (Email) |
| **Email**       | Email address to verify      |

**Returns**

| Field       | Description                      |
| ----------- | -------------------------------- |
| Status      | Verification result              |
| Deliverable | Whether the email is deliverable |
| Risk level  | Risk assessment of the email     |

***

## Credits

| Action | Cost        |
| ------ | ----------- |
| Verify | 0.1 credits |

***

## Use cases

<AccordionGroup>
  <Accordion title="List cleaning" icon="broom">
    Verify email lists before outreach campaigns.
  </Accordion>

  <Accordion title="Lead validation" icon="check-circle">
    Validate emails at point of capture.
  </Accordion>

  <Accordion title="Deliverability optimization" icon="envelope-circle-check">
    Improve sender reputation by removing invalid emails.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Verify before campaigns** - Always verify emails before adding to sequences
2. **Handle risky emails** - Consider removing or isolating risky addresses
3. **Cache results** - Verification results are cached to reduce costs


# Enrow.io
Source: https://docs.getcargo.ai/integration/enrowio

Connect Enrow.io to find and verify email addresses in your workflows.

## How to set up Enrow\.io

### Authentication

Enrow\.io uses API key authentication:

1. Sign up at [enrow.io](https://enrow.io)
2. Navigate to your API settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## Enrow\.io actions

### Find email

Find a person's email address using their name and company.

**Required fields:**

* **Full name**: Person's full name

**Optional fields:**

* **Company domain**: Company's domain (e.g., "apple.com" or "[https://www.apple.com](https://www.apple.com)")
* **Company name**: Company's name (e.g., "Apple", "Air France")
* **Country code**: ISO 3166 Alpha-2 country code (helps when using company name)

**Credits:** 1 credit per request

**Use case:** Discover professional email addresses for prospecting.

### Verify email

Check if an email address is valid and deliverable.

**Required fields:**

* **Email**: The email address to verify

**Optional fields:**

* **Country code**: ISO 3166 Alpha-2 country code

**Credits:** 0.1 credits per request

**Use case:** Validate emails before sending campaigns.

## Credits summary

| Action       | Credits |
| ------------ | ------- |
| Find email   | 1       |
| Verify email | 0.1     |

## Retry behavior

Enrow\.io actions include automatic retry logic:

* Maximum 8 retry attempts
* Exponential backoff (starting at 2 seconds)
* Handles rate limits automatically

## Rate limits

Enrow\.io API has a rate limit of 60 requests per minute. Cargo handles rate limiting automatically.

## Best practices

* Provide company domain for best email finding accuracy
* Use country code when using company name instead of domain
* Always verify found emails before outreach (very affordable at 0.1 credits)
* Combine find + verify for complete validation
* Cache results to avoid redundant lookups


# Exa
Source: https://docs.getcargo.ai/integration/exa

Connect Exa to run AI-native web search in your Cargo workflows.

Exa is an AI-native search engine that helps you retrieve high-quality web results with semantic ranking and optional page content extraction.

## How to set up Exa

### Authentication

Exa runs on Cargo credits out of the box, so you can use it without an Exa account. To bill Exa directly instead — or to use Exa as an MCP server, which requires your own key — connect an API key:

1. Create an Exa account at [exa.ai](https://exa.ai)
2. Generate an API key from your Exa dashboard
3. Paste the API key when creating the Exa connector in Cargo

### Connection details

| Field       | Description      |
| ----------- | ---------------- |
| **API key** | Your Exa API key |

***

## Exa actions

### Search

Search the web with Exa and return ranked results.

**Required fields:**

* **Query**: Natural language query to search for

**Optional fields:**

* **Search type**: `auto`, `neural`, `fast`, `deep`, or `instant`
* **Category**: Focus results on a category such as company, people, or news
* **Number of results**: Max results to return (up to 100)
* **Include page text**: Include extracted page text in the response
* **Include domains**: Restrict results to specific domains
* **Exclude domains**: Remove results from specific domains
* **Start/End published date**: Filter by publication date range
* **Start/End crawl date**: Filter by crawl date range

**Use cases:**

* Account and company research
* Competitive intelligence
* News and trend monitoring
* Source collection for AI agents

***

## Response data

Search responses include:

* URL and title
* Relevance score
* Publication and crawl metadata (when available)
* Extracted text (when enabled)

***

## Best practices

* Use `auto` search type for most workflows
* Limit domain scope for precise results
* Enable page text only when needed to reduce payload size
* Cap **Number of results**: the first 10 come with the request, and every result past that adds to the bill

***

## Credits

Exa is billable with Cargo credits, so you can use it without your own Exa account. Costs mirror Exa's published pricing at \$0.04 per Cargo credit.

* **Search**: 0.175 credits per search, which covers the first 10 results with their text and highlights
* **Search** with the `deep` search type: 0.3 credits per search, since Exa's agentic search costs more to run
* Either way, each result past the tenth adds 0.025 credits, contents included

Cargo tracks credit usage and supports caching to optimize costs.

<Note>
  Using Exa as an [MCP server](/agents/tools-and-actions#mcp-servers) requires
  your own Exa API key. Tools
  called over MCP bypass Cargo's action pipeline, so there is nothing to meter
  them against your credit balance.
</Note>

***

## Rate limits

Exa allows 10 search requests per second. Cargo spreads calls to stay under the limit and retries on rejection. On Cargo credits that limit is shared across all workspaces on Cargo's key; on your own API key it applies to your connector alone.


# Expandi.io
Source: https://docs.getcargo.ai/integration/expandi

Add LinkedIn profiles to your Expandi outreach campaigns

Expandi.io is a LinkedIn automation and outreach platform that helps you scale your LinkedIn prospecting. The Cargo integration allows you to automatically add profiles to your Expandi campaigns.

## Authentication

Expandi uses campaign-level webhook URLs for authentication. Each campaign has its own unique webhook URL that includes the necessary credentials.

<Info>
  Webhook URLs are generated per campaign in your Expandi dashboard.
</Info>

***

## Expandi actions

### Add profile to campaign

Add a LinkedIn profile to an Expandi campaign for automated outreach.

**Configuration**

| Field                    | Description                                               |
| ------------------------ | --------------------------------------------------------- |
| **Campaign webhook URL** | The webhook URL from your Expandi campaign                |
| **Profile link**         | LinkedIn profile URL to add to the campaign               |
| **Fields**               | Optional custom fields (first\_name, company\_name, etc.) |

**Supported fields**

| Field                | Description                        |
| -------------------- | ---------------------------------- |
| `first_name`         | Contact's first name               |
| `company_name`       | Contact's company name             |
| `custom_placeholder` | Any custom placeholder you defined |

<Tip>
  Pass custom fields to personalize your Expandi campaign messages with data from Cargo.
</Tip>

***

## Use cases

<AccordionGroup>
  <Accordion title="Qualified lead outreach" icon="bullseye">
    Add leads that meet specific criteria to targeted LinkedIn campaigns.
  </Accordion>

  <Accordion title="Event follow-up" icon="calendar">
    Automatically add event attendees to post-event LinkedIn sequences.
  </Accordion>

  <Accordion title="ABM campaigns" icon="building">
    Add contacts from target accounts to account-based outreach campaigns.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Validate LinkedIn URLs** - Ensure profile URLs are valid LinkedIn URLs before adding to campaigns
2. **Use custom fields** - Pass personalization data from Cargo to improve campaign engagement
3. **Respect rate limits** - Expandi has daily limits on connection requests and messages


# FindyMail
Source: https://docs.getcargo.ai/integration/findy-mail

Connect FindyMail to find and verify email addresses in your workflows.

## How to set up FindyMail

### Authentication

FindyMail uses API key authentication:

1. Sign up at [findymail.com](https://findymail.com)
2. Navigate to your API settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## FindyMail actions

### Find email

Find a person's email address using their name and company.

**Input fields:**

* **Name**: Person's full name
* **Domain**: Company domain
* **LinkedIn URL**: Person's LinkedIn profile URL (optional but improves accuracy)

**Credits:** 0.5 credits per request

**Use case:** Discover professional email addresses for outbound prospecting.

### Verify email

Check if an email address is valid and won't bounce.

**Required fields:**

* **Email**: The email address to verify

**Credits:** 0.25 credits per request

**Use case:** Validate emails before campaigns to protect sender reputation.

### Find phone

Get a person's phone number from their LinkedIn URL.

**Required fields:**

* **LinkedIn URL**: Person's LinkedIn profile URL

**Credits:** 5 credits per request

**Use case:** Get direct phone numbers for high-priority prospects.

## Credits summary

| Action       | Credits |
| ------------ | ------- |
| Find email   | 0.5     |
| Verify email | 0.25    |
| Find phone   | 5       |

## Best practices

* Provide LinkedIn URL when available for best results
* Always verify found emails before sending
* Use caching to avoid redundant lookups
* Combine find + verify for complete validation


# Firecrawl
Source: https://docs.getcargo.ai/integration/firecrawl

This page outlines how to use the Firecrawl integration for web scraping in Cargo.

Firecrawl is a web scraping API that turns any website into clean, structured data. Cargo's native integration with Firecrawl allows you to scrape individual pages or crawl entire websites directly from your workflows.

## How to set up Firecrawl

You can use Firecrawl in two ways:

1. **Cargo credits** – Use Firecrawl through Cargo's managed integration
2. **Your own API key** – Connect your [Firecrawl account](https://www.firecrawl.dev/app/api-keys)

### Connection details

| Field       | Description            |
| ----------- | ---------------------- |
| **API Key** | Your Firecrawl API key |

<Tip>Get your API key from the Firecrawl dashboard.</Tip>

***

## Firecrawl actions

### Scrape

Extract content from a single URL.

**Use cases**

* **Page content extraction** – Get clean text from any webpage
* **Product data** – Scrape product information from e-commerce sites
* **News monitoring** – Extract articles and updates
* **Research** – Gather information from multiple sources

**Configuration**

| Field   | Description               |
| ------- | ------------------------- |
| **URL** | URL of the page to scrape |

**Credit cost:** 0.05 credits per page

### Crawl

Recursively crawl a website and extract content from multiple pages.

**Use cases**

* **Site-wide extraction** – Crawl documentation or knowledge bases
* **Competitive analysis** – Extract content from competitor sites
* **Content aggregation** – Gather content across multiple pages
* **Data collection** – Build datasets from websites

**Configuration**

| Field             | Description                              |
| ----------------- | ---------------------------------------- |
| **URL**           | Starting URL for the crawl               |
| **Maximum depth** | How deep to crawl (0 = single page only) |
| **Includes**      | Path patterns to include                 |
| **Excludes**      | Path patterns to exclude                 |
| **Limit**         | Maximum pages to crawl                   |

**Options**

| Option                   | Description                                    |
| ------------------------ | ---------------------------------------------- |
| **Ignore sitemap**       | Don't use the site's sitemap for discovery     |
| **Allow backward links** | Allow crawling back to previously linked pages |
| **Allow external links** | Follow links to external websites              |

<Info>Use Include and Exclude patterns to focus your crawl on specific sections of a website.</Info>

**Credit cost:** 0.05 credits per page crawled

***

## Firecrawl data models

Create data models from crawled websites to power your workflows.

### Crawl extractor

Crawl a website and create records from each page.

**Configuration**

| Field             | Description                     |
| ----------------- | ------------------------------- |
| **URL**           | Starting URL for the crawl      |
| **Maximum depth** | How deep to crawl               |
| **Includes**      | Path patterns to include        |
| **Excludes**      | Path patterns to exclude        |
| **Limit**         | Maximum pages (default: 10,000) |


# Forager
Source: https://docs.getcargo.ai/integration/forager

Find personal emails and phone numbers with Forager

Forager is a contact data enrichment platform that provides personal emails and phone numbers from LinkedIn profiles.

## Authentication

Connect to Forager using your account ID and API key.

### Connection details

| Field          | Description             |
| -------------- | ----------------------- |
| **Account ID** | Your Forager account ID |
| **API key**    | Your Forager API key    |

***

## Forager actions

### Find personal email

Retrieve a person's personal email address.

**Configuration**

| Field            | Description          |
| ---------------- | -------------------- |
| **LinkedIn URL** | LinkedIn profile URL |

### Find work email

Retrieve a person's work email address.

**Configuration**

| Field            | Description          |
| ---------------- | -------------------- |
| **LinkedIn URL** | LinkedIn profile URL |

### Find phone

Retrieve a person's phone number.

**Configuration**

| Field            | Description          |
| ---------------- | -------------------- |
| **LinkedIn URL** | LinkedIn profile URL |

***

## Credits

| Action              | Cost      |
| ------------------- | --------- |
| Find personal email | 2 credits |
| Find work email     | 2 credits |
| Find phone          | 5 credits |

***

## Use cases

<AccordionGroup>
  <Accordion title="Multi-channel outreach" icon="envelope">
    Combine work and personal email for better response rates.
  </Accordion>

  <Accordion title="Phone outreach" icon="phone">
    Get direct phone numbers for high-priority prospects.
  </Accordion>

  <Accordion title="LinkedIn enrichment" icon="user-plus">
    Enrich LinkedIn profiles with contact information.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use LinkedIn URLs** - LinkedIn profile URLs provide the best match rates
2. **Prioritize work email** - Work emails typically have higher deliverability
3. **Cache results** - Results are cached to reduce credit usage


# FullEnrich
Source: https://docs.getcargo.ai/integration/full-enrich

This page outlines how to use the FullEnrich integration to enrich for phones and emails in Cargo.

FullEnrich is one of the leading waterfall enrichment solutions for emails and phone numbers. Waterfall enrichment uses a cascade of data providers to find the cheapest and most reliable email and phone information—maximizing coverage while minimizing cost.

## How to set up FullEnrich

<div>
  <iframe title="Setup a data model" />
</div>

### Connection options

You can connect FullEnrich to Cargo in two ways:

* **Use Cargo credits** – Leverage Cargo's built-in credits for seamless billing
* **Use your own API key** – Connect your existing FullEnrich account for direct billing

### After connecting

Once the connector is set up, you can choose **FullEnrich** from the node catalog within a **Play**, **Tool**, or **Agent** to start enriching your data.

***

## FullEnrich actions

### Find phone and email

<div>
  <iframe title="Setup a data model" />
</div>

Find a person's email and phone number in a single request.

**Required inputs**

One of:

* LinkedIn URL
* First name and last name, plus one of company name or domain name

**Use cases**

* **Lead enrichment** – Find both email and phone for comprehensive lead information
* **Outbound campaigns** – Power multi-channel outreach with complete contact data

***

### Find email

Find a person's professional email address.

**Required inputs**

One of:

* LinkedIn URL
* First name and last name, plus one of company name or domain name

**Key outputs**

* `most_probable_email` – The best matching email address
* `most_probable_email_status` – Validation status to verify deliverability

**Use cases**

* **Lead enrichment** – Enrich valid emails for your prospects. Use `most_probable_email_status` to ensure validity before pushing to your CRM or campaigns
* **Email validation** – Validate existing emails in your CRM to clean up invalid or outdated addresses

***

### Find phone

Find a lead's direct phone number.

**Required inputs**

One of:

* LinkedIn URL
* First name and last name, plus one of company name or domain name

**Key outputs**

* `most_probable_phone` – The best matching phone number

**Use cases**

* **Lead enrichment** – Find direct phone numbers for your prospects
* **Phone validation** – Validate existing contact records to identify and remove generic or outdated phone numbers from your CRM
* **Sales enablement** – Equip your sales team with direct dials for faster outreach

***

### Reverse email lookup

Find information about a person based on their email address.

**Required inputs**

* Email address

**Key outputs**

* `first_name` – The person's first name
* `last_name` – The person's last name
* `company_name` – The person's current company
* `job_title` – The person's job title
* `linkedin_url` – The person's LinkedIn profile URL

**Use cases**

* **Inbound lead qualification** – Identify who's behind form submissions or sign-ups to prioritize high-value leads
* **Email list enrichment** – Enrich email-only lists with full contact and company information
* **Account mapping** – Discover company associations from email addresses to build account hierarchies


# G2
Source: https://docs.getcargo.ai/integration/g2

Connect G2 to access product reviews, ratings, and software marketplace data in your workflows.

## How to set up G2

### Authentication

G2 integration uses Cargo credits - no separate authentication required:

1. Add the G2 integration in Cargo
2. Start using G2 actions immediately

## G2 actions

### Enrich product

Get detailed information about a software product from G2.

**Required fields:**

* **Product URL**: G2 product URL or product slug (e.g., "hubspot-crm" or full URL)

**Returns:**

* Product name and description
* Overall rating and review count
* Category and segment information
* Pricing details
* Feature ratings
* Competitor comparisons

**Credits:** 1 credit per request

**Use cases:**

* Research competitor products
* Understand software market landscape
* Gather competitive intelligence
* Identify technology usage signals

## G2 data models

### Fetch products

Pull products from specific G2 categories.

**Configuration:**

* **Categories**: Select G2 categories to fetch products from

**Features:**

* Minimum 30-day sync interval
* Fetches all products in selected categories

**Credits:** 1 credit per request

**Use cases:**

* Build lists of companies using specific software types
* Monitor new entrants in software categories
* Track market changes over time

## Response data

### Product enrichment returns:

| Field          | Description              |
| -------------- | ------------------------ |
| name           | Product name             |
| description    | Product description      |
| rating         | Overall G2 rating        |
| reviews\_count | Number of reviews        |
| category       | Product category         |
| pricing        | Pricing information      |
| features       | Feature list and ratings |
| pros           | Common positive feedback |
| cons           | Common negative feedback |
| competitors    | Alternative products     |

## Credits

G2 actions use Cargo credits:

* Enrich product: 1 credit
* Fetch products: 1 credit per request

Caching is supported to optimize credit usage.

## Best practices

* Use product slugs for consistent matching
* Cache results for frequently researched products
* Combine with company enrichment for complete profiles
* Monitor category changes for market intelligence
* Use competitor data in sales conversations

## Rate limits

G2 integration has a rate limit of 10 requests per minute. Cargo handles rate limiting automatically.


# Google Gemini
Source: https://docs.getcargo.ai/integration/gemini

Connect Google Gemini to use Google's AI models for text generation and analysis in your workflows.

## How to set up Google Gemini

### Authentication

Google Gemini uses API key authentication:

1. Go to [Google AI Studio](https://ai.google.dev)
2. Sign in with your Google account
3. Create an API key
4. Copy the API key and paste it in Cargo when connecting

## Google Gemini actions

### Instruct

Generate text responses using Google's Gemini models.

**Required fields:**

* **Model**: Select the Gemini model
* **Prompt**: Your instruction or question

**Available models:**

| Model                | Description                               | Context Window |
| -------------------- | ----------------------------------------- | -------------- |
| gemini-3-pro-preview | Latest generation with advanced reasoning | 2M tokens      |
| gemini-2.5-flash     | Fast, cost-efficient for diverse tasks    | 1M tokens      |
| gemini-2.5-pro       | Most capable for complex reasoning        | 2M tokens      |
| gemini-2.0-flash     | Fast multimodal from 2.0 generation       | 1M tokens      |
| gemini-1.5-flash     | Efficient, optimized for speed            | 1M tokens      |
| gemini-1.5-pro       | Advanced with large context               | 2M tokens      |

**Advanced settings:**

* **System prompt**: Set context for the model's behavior
* **Maximum output tokens**: Limit response length
* **Temperature**: Control randomness (0-2, default 1)
* **With Google Search**: Enable real-time information retrieval

**Output options:**

* **Text**: Plain text response
* **JSON object**: Unstructured JSON output
* **JSON schema**: Structured output matching your schema

## Use cases

* **Lead qualification**: Analyze lead data and provide scoring insights
* **Email generation**: Create personalized outreach at scale
* **Data parsing**: Extract structured data from unstructured sources
* **Translation**: Translate content for international campaigns
* **Summarization**: Condense long documents or conversations

## Credits and pricing

Costs vary by model (per 1,000 tokens):

| Model                | Standard     | With Google Search |
| -------------------- | ------------ | ------------------ |
| gemini-3-pro-preview | 0.2 credits  | 0.2 + 1 fixed      |
| gemini-2.5-pro       | 0.15 credits | 0.15 + 1 fixed     |
| gemini-2.5-flash     | 0.03 credits | 0.03 + 1 fixed     |
| gemini-2.0-flash     | 0.01 credits | 0.01 + 1 fixed     |
| gemini-1.5-pro       | 0.1 credits  | 0.1 + 1 fixed      |
| gemini-1.5-flash     | 0.01 credits | 0.01 + 1 fixed     |

## Rate limits

| Model                | Requests per minute |
| -------------------- | ------------------- |
| gemini-3-pro-preview | 1,000               |
| gemini-2.5-flash     | 15,000              |
| gemini-2.5-pro       | 1,000               |
| gemini-2.0-flash     | 15,000              |
| gemini-1.5-flash     | 15,000              |
| gemini-1.5-pro       | 2,000               |

## Best practices

* Use Flash models for simple, high-volume tasks
* Use Pro models for complex reasoning and analysis
* Enable Google Search for questions requiring current information
* Define JSON schemas for consistent, structured outputs
* Adjust temperature based on task (lower for factual, higher for creative)
* Leverage the large context windows for processing lengthy documents


# GitHub
Source: https://docs.getcargo.ai/integration/github

Connect GitHub to search repositories, contributors, and stargazers for developer-focused prospecting.

## How to set up GitHub

### Authentication

GitHub uses OAuth authentication:

1. Click the Connect button in Cargo
2. Authorize Cargo to access your GitHub account
3. Connection is established automatically

Alternatively, you can use a Personal Access Token:

1. Go to GitHub → Settings → Developer settings → Personal access tokens
2. Generate a new token with appropriate scopes
3. Use this token in the API Key field

## GitHub actions

### Search contributors

Find contributors to a specific GitHub repository.

**Required fields:**

* **Repository Owner**: The username or organization (e.g., "facebook")
* **Repository Name**: The repository name (e.g., "react")

**Optional fields:**

* **Include Anonymous Contributors**: Include contributors without GitHub accounts
* **Limit**: Maximum number of results

**Use cases:**

* Find developers working on specific technologies
* Identify potential hires skilled in particular frameworks
* Build lists of open source contributors for outreach

### Get user

Retrieve detailed information about a GitHub user.

**Required fields:**

* **Username**: GitHub username to look up

**Returns:**

* Profile information
* Email (if public)
* Company
* Location
* Bio
* Follower/following counts
* Public repos count

**Use case:** Enrich GitHub usernames with profile details for outreach.

## GitHub data models

### Fetch repositories

Pull repositories matching a search query.

**Configuration:**

* **Query**: Search query with GitHub qualifiers

**Query examples:**

* `language:typescript stars:>1000` - Popular TypeScript repos
* `org:facebook` - All Facebook organization repos
* `topic:machine-learning` - ML-related repositories

**Sync interval:** Minimum 30 minutes

**Use case:** Build lists of repositories for technology-based prospecting.

### Fetch stargazers

Pull users who have starred a repository.

**Required fields:**

* **Owner**: Repository owner (e.g., "vercel")
* **Repository**: Repository name (e.g., "next.js")

**Features:**

* Unifies contacts by email
* Minimum 30-minute sync interval

**Use cases:**

* Find developers interested in specific technologies
* Build targeted lists of potential users
* Identify early adopters and enthusiasts

## Response data

### User details include:

| Field         | Description                   |
| ------------- | ----------------------------- |
| login         | GitHub username               |
| email         | Email (if public)             |
| name          | Display name                  |
| company       | Company name                  |
| location      | Location                      |
| bio           | Profile bio                   |
| blog          | Personal website              |
| twitter       | Twitter username              |
| followers     | Follower count                |
| public\_repos | Number of public repositories |

### Contributor details include:

| Field         | Description         |
| ------------- | ------------------- |
| login         | GitHub username     |
| contributions | Number of commits   |
| avatar\_url   | Profile picture URL |
| html\_url     | GitHub profile URL  |

## Rate limits

GitHub API has a rate limit of 5,000 requests per hour for authenticated requests. Cargo handles rate limiting automatically.

## Best practices

* Use specific search queries to find relevant repositories
* Focus on active contributors (high contribution counts)
* Combine with enrichment tools to find email addresses
* Respect GitHub's rate limits for large data pulls
* Target stargazers of complementary/competing projects


# Google Ads
Source: https://docs.getcargo.ai/integration/google-ads

Push contacts into Google Ads Customer Match user lists for ad targeting and remarketing

Google Ads Customer Match lets you target ads to a custom list of contacts based on first-party data. The Cargo integration lets you create Customer Match user lists, push contacts into them, remove contacts, and pull size and match-rate metrics — all from your workflows.

## Authentication

Connect to Google Ads using OAuth.

<Info>
  The signed-in Google account must have access to the Google Ads accounts you want to push audiences into. Cargo requests the `https://www.googleapis.com/auth/adwords` scope and only stores an encrypted refresh token — Google handles access-token refresh.
</Info>

<Warning>
  Customer Match requires a Google Ads developer token with Customer Match access. New developer tokens may need to be approved by Google before they can upload Customer Match data — see [Get started with Customer Match](https://developers.google.com/google-ads/api/docs/remarketing/audience-segments/customer-match/get-started) for the current process.
</Warning>

***

## Google Ads actions

### Create Audience

Create a new CRM-based Customer Match user list on a Google Ads account.

**Configuration**

| Field                          | Description                                                                  |
| ------------------------------ | ---------------------------------------------------------------------------- |
| **Ad account**                 | Google Ads customer ID (10 digits, no dashes), e.g. `1234567890`             |
| **Audience name**              | Display name for the new user list                                           |
| **Description**                | Optional description                                                         |
| **Membership lifespan (days)** | How long a member remains in the list. Max 540 days for CRM-based user lists |

**Returns**

The newly created `userListId`, plus the full `resourceName`, the `name`, and the `customerId`.

<Tip>
  CRM-based user lists are the only Customer Match list type that accepts hashed customer data via the API. You'll see the new list in the Google Ads UI under **Tools → Audience manager → Customer lists**.
</Tip>

### Add Contact to Audience

Add a single contact to a Customer Match user list. At least one identifier (email, phone, mobile advertising ID, or full address) is required.

**Configuration**

| Field                         | Description                                                             |
| ----------------------------- | ----------------------------------------------------------------------- |
| **Ad account**                | Google Ads customer ID                                                  |
| **Audience**                  | Customer Match user list to add the contact to                          |
| **Email**                     | Lowercased and SHA-256 hashed automatically before being sent to Google |
| **Phone number**              | E.164 format (e.g. `+15551234567`); SHA-256 hashed automatically        |
| **Mobile advertising ID**     | Optional IDFA or GAID                                                   |
| **First name**, **Last name** | Lowercased and SHA-256 hashed automatically                             |
| **Country code**              | ISO 3166-1 alpha-2 (e.g. `US`)                                          |
| **Postal code**               | Optional, paired with country code                                      |

<Warning>
  At least one identifier (email, phone, mobile ID, or a full address — first name + last name + country code + postal code) is required.
</Warning>

<Info>
  Cargo lowercases and SHA-256 hashes emails, phone numbers, and names before sending them to Google, as required by the Customer Match API. You only need to provide the raw value — the hashing happens automatically.
</Info>

**How it works under the hood**

Each call creates an `OfflineUserDataJob` of type `CUSTOMER_MATCH_USER_LIST`, adds a single create operation with the hashed identifiers, and runs the job. Google processes the upload asynchronously — there is no synchronous "added/not added" response.

### Remove Contact from Audience

Remove a contact from a Customer Match user list by email.

**Configuration**

| Field          | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| **Ad account** | Google Ads customer ID                                                  |
| **Audience**   | Customer Match user list to remove the contact from                     |
| **Email**      | Lowercased and SHA-256 hashed automatically before being sent to Google |

<Tip>
  Only contacts that were added with the same hashed email are removed. If a contact was added with a different identifier (phone, mobile ID, address), removing by email will not affect them.
</Tip>

### Create Report

Fetch size and match-rate metrics for a Customer Match user list.

**Configuration**

| Field          | Description                           |
| -------------- | ------------------------------------- |
| **Ad account** | Google Ads customer ID                |
| **Audience**   | Customer Match user list to report on |

**Returns**

| Field                 | Description                                                       |
| --------------------- | ----------------------------------------------------------------- |
| `userListId`          | The user list ID                                                  |
| `resourceName`        | The full resource name (`customers/{cid}/userLists/{id}`)         |
| `sizeForDisplay`      | Estimated number of matched members for Display Network targeting |
| `sizeForSearch`       | Estimated number of matched members for Search Network targeting  |
| `matchRatePercentage` | Google's estimated match rate, as a percentage                    |

<Info>
  Google populates match data asynchronously after you push records into a list. New lists typically take 24–48 hours before metrics show meaningful values, and a list needs at least 1,000 members before Google reveals its match rate.
</Info>

***

## Use cases

<AccordionGroup>
  <Accordion title="Lead retargeting" icon="bullseye">
    Sync engaged contacts (MQLs, trial signups, demo requests) into a user list and retarget them across Google Search, YouTube, and the Display Network.
  </Accordion>

  <Accordion title="Customer remarketing" icon="users">
    Push your existing customers into a user list to drive expansion campaigns, or build lookalike (Similar) audiences off them.
  </Accordion>

  <Accordion title="Suppression lists" icon="user-slash">
    Keep a user list of customers or unsubscribed contacts in sync, then exclude it from campaigns to avoid wasting spend on people you already converted.
  </Accordion>

  <Accordion title="Match-rate monitoring" icon="chart-line">
    Use **Create Report** in a scheduled workflow to track audience match rates over time and alert when they drop.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Provide as many identifiers as possible** — Google matches on any of email, phone, mobile ID, or full address. The more identifiers per contact, the higher the match rate.
2. **Send raw values, not pre-hashed** — Cargo normalizes (lowercase, trim, E.164 for phone) and SHA-256 hashes for you. Sending already-hashed data will skip the normalization step and lower your match rate.
3. **Use full addresses, not partials** — When supplying address fields, include first name, last name, country code, and postal code together. Partial addresses are dropped by Google.
4. **Wait before reading match rates** — Schedule **Create Report** at least 24 hours after pushing records. Lists below 1,000 members will return a placeholder match rate until they cross the threshold.
5. **Remove with the same identifier you added** — Google only removes contacts whose hashed identifier matches. If a contact was added with phone + address, removing by email alone won't take them out of the list.

***

## Limitations

* **Customer Match API migration**: Google announced that as of April 1, 2026, the `OfflineUserDataJobService` path used by this integration is being deprecated in favor of the new **Data Manager API**. Developer tokens that have been actively used for Customer Match uploads continue to work, but tokens that have been inactive for 180+ days will be blocked. See the [Google Ads Developer Blog](https://ads-developers.googleblog.com/2026/03/changes-to-customer-match-support-in.html) for details. Long-term, this integration will need to be migrated to the Data Manager API.
* **Manager (MCC) accounts**: this integration sets the `login-customer-id` header to the same value as the customer being pushed to. For accounts under a Manager (MCC) account, you may need to use the direct (non-manager) customer ID rather than the MCC ID.
* **One contact per action call**: each `Add Contact to Audience` call creates its own offline user data job. For very high-volume syncs (tens of thousands of records per minute), consider batching upstream — Google rate-limits job creation per customer.


# Google Sheets
Source: https://docs.getcargo.ai/integration/google-sheets

This page outlines how to use the Google Sheets integration to read and write spreadsheet data in Cargo.

Google Sheets is a cloud-based spreadsheet application that enables collaborative data management and analysis. Cargo's native integration with Google Sheets allows you to read data from spreadsheets as part of data models, and write or update data in your sheets as part of automated workflows.

## How to set up Google Sheets

Cargo supports two authentication modes for connecting to Google Sheets, each suited for different use cases:

<AccordionGroup>
  <Accordion title="OAuth (Standard)" icon="key">
    **Best for:** Personal use, small to medium data volumes, quick setup - Uses
    your Google account credentials - Simple one-click authorization - Standard
    API rate limits (100 requests per 100 seconds per user) - Access to sheets
    you own or have been shared with
  </Accordion>

  <Accordion title="Service Account (Recommended for Production)" icon="server">
    **Best for:** Production workflows, large data volumes, automated processes

    * Higher rate limits (150 requests per minute) - No user interaction
      required - Ideal for server-to-server communication - Requires Google Cloud
      setup
  </Accordion>
</AccordionGroup>

***

## Authentication Mode 1: OAuth

OAuth is the simplest way to connect Google Sheets and is perfect for personal use or smaller workflows.

### Step 1: Connect via OAuth

1. In Cargo, navigate to the **Google Sheets connector** settings.
2. Under **Authentication**, select **OAuth**.
3. Click **Connect** and authorize Cargo to access your Google Sheets.
4. Grant the required permissions when prompted.

Once connected, you can:

* **Set up a Google Sheets data model** — Create data models from your spreadsheets to trigger Plays and power model search actions.
* **Use Google Sheets in workflows** — Choose **Google Sheets** from the node catalog within a **Play**, **Tool**, or **Agent**.

<Info>
  OAuth connections have access to all sheets that your Google account has
  permission to view or edit. Make sure you're using the correct Google account
  when connecting.
</Info>

***

## Authentication Mode 2: Service Account

Using a Service Account is the recommended way to connect Google Sheets if you need to process larger amounts of data without hitting standard API limits.

### Prerequisite: Google Cloud Account

You must have a Google Cloud account to proceed.

* **If you don't have one:** [Create a Google Cloud account here](https://cloud.google.com/).

* **If you have one:** Log in and select your project.

### Step 1: Generate Your Service Account Key

1. Navigate to the **Service Accounts > Keys** section in your Google Cloud Console.

2. Click the **Add key** button and select **Create new key**.

3. In the popup window, select **JSON** as the "Key type".

4. Click **Create**.

   * *Result:* A file ending in `.json` will automatically download to your computer. This file contains the credentials Cargo needs.

### Step 2: Connect to Cargo

1. Open the `.json` file you just downloaded using a text editor (like Notepad on Windows or TextEdit on Mac) and **copy the entire text**.

2. Go back to Cargo and open the **Google Sheets connector** settings.

3. Under **Authentication**, select **Service account** (this enables the higher rate limit of 150 requests/min).

4. Paste the text you copied into the **Service account** field.

5. Click **Save**.

### Step 3: Activate the Google Sheets API

For the connection to work, you must tell Google to allow this project to use Sheets.

* **Open the [Google Sheets API page](https://console.cloud.google.com/apis/library/sheets.googleapis.com)** in the Cloud Console, making sure your project is selected in the top bar.

* Ensure the button says **Enabled** or click **Enable** if it is not already active.

* You're good to go.

<Warning>
  When using a Service Account, you must share your Google Sheets with the
  service account email address (found in the JSON key file) for it to access
  your spreadsheets. The service account email typically looks like:
  `your-service-account@your-project.iam.gserviceaccount.com`
</Warning>

***

## Google Sheets actions

<Tip>
  All Google Sheets actions support reading from and writing to any spreadsheet
  that your authentication method has access to.
</Tip>

### Insert record

Insert a new row into a Google Sheet.

**Use cases**

* **Lead capture** – Create new leads from various sources and channels
* **Data logging** – Add new entries to tracking sheets
* **Contact creation** – Add new contacts from forms, events, or imports

### Update record

Update an existing row in a Google Sheet.

**Use cases**

* **Data enrichment** – Keep spreadsheet information current and accurate
* **Status updates** – Update record statuses and stages
* **Field updates** – Modify specific cell values in existing rows

### Upsert records

Upsert multiple rows into a Google Sheet (insert or update based on matching criteria).

**Use cases**

* **Bulk data operations** – Insert rows in bulk while avoiding duplicates
* **Data synchronization** – Keep external systems synchronized with Google Sheets
* **Migration workflows** – Import data from other systems while handling existing records

<Warning>
  Upsert operations will match on the fields you specify. Ensure your matching
  criteria is unique to avoid unintended updates.
</Warning>

***

## Google Sheets data models

Cargo allows you to create data models on top of your Google Sheets data that can be used to trigger Plays and power model search actions.

### Creating Google Sheets data models

| Field           | Description                                                            |
| --------------- | ---------------------------------------------------------------------- |
| **Name**        | Choose a descriptive name for your data model (required)               |
| **Slug**        | Set a unique identifier that cannot be changed once created (required) |
| **Spreadsheet** | Select the Google Sheet you want to model                              |
| **Worksheet**   | Select the specific worksheet within the spreadsheet                   |

<Info>
  The first row of your selected range will be used as column headers. Make sure
  your sheet has a header row for best results. The **fetchWorksheet** extractor
  is used to retrieve data from your specified worksheet and range.
</Info>

***

## Rate limits

| Authentication Method | Rate Limit                            |
| --------------------- | ------------------------------------- |
| **OAuth**             | 100 requests per 100 seconds per user |
| **Service Account**   | 150 requests per minute               |

<Warning>
  Exceeding rate limits will result in errors. For high-volume workflows, use
  Service Account authentication to benefit from higher limits.
</Warning>

***

## Security

* All Google Sheets connections use Google's secure authentication protocols
* Service account keys are encrypted at rest in Cargo
* OAuth tokens are securely stored and can be revoked at any time from your Google account settings
* Cargo only requests the minimum permissions needed to read and write to your sheets


# HeyReach
Source: https://docs.getcargo.ai/integration/hey-reach

Manage LinkedIn outreach campaigns with HeyReach

HeyReach is a LinkedIn automation platform for managing outreach campaigns at scale. The Cargo integration allows you to add leads to campaigns, stop leads, retrieve lead information, and listen to real-time campaign events.

## Authentication

Connect to HeyReach using your API key.

### Connection details

| Field       | Description           |
| ----------- | --------------------- |
| **API Key** | Your HeyReach API key |

***

## HeyReach actions

### Get lead

Retrieve information about a lead by their LinkedIn profile URL.

**Configuration**

| Field           | Description          |
| --------------- | -------------------- |
| **Profile URL** | LinkedIn profile URL |

### Add lead to campaign

Add a new lead to a HeyReach campaign with full personalization data.

**Configuration**

| Field                | Description                                  |
| -------------------- | -------------------------------------------- |
| **Campaign**         | Select the target campaign                   |
| **LinkedIn account** | LinkedIn account to use for outreach         |
| **First name**       | Lead's first name (required)                 |
| **Last name**        | Lead's last name (required)                  |
| **Profile URL**      | LinkedIn profile URL (required)              |
| **Location**         | Lead's location                              |
| **Summary**          | Lead's LinkedIn summary                      |
| **Company name**     | Current company                              |
| **Position**         | Current job title                            |
| **About**            | Lead's about section                         |
| **Email address**    | Lead's email address                         |
| **Custom mappings**  | Additional custom fields for personalization |

<Tip>
  Pass as much personalization data as possible to improve campaign engagement rates.
</Tip>

### Stop lead in campaign

Stop outreach to a lead in a specific campaign.

**Configuration**

| Field           | Description                  |
| --------------- | ---------------------------- |
| **Campaign**    | Select the campaign          |
| **Profile URL** | LinkedIn profile URL to stop |

***

## HeyReach extractors

### Listen events

Listen to real-time HeyReach webhook events and ingest them as contact events. When enabled, Cargo registers webhooks in your HeyReach workspace for every supported event type and automatically ingests each event as it occurs. Cargo reconciles its webhooks on every sync — recreating any that are missing and removing stale or duplicate ones — so the configured set stays in sync with HeyReach.

**Captured events**

`CONNECTION_REQUEST_SENT`, `CONNECTION_REQUEST_ACCEPTED`, `MESSAGE_SENT`, `MESSAGE_REPLY_RECEIVED`, `INMAIL_SENT`, `INMAIL_REPLY_RECEIVED`, `FOLLOW_SENT`, `LIKED_POST`, `VIEWED_PROFILE`, `CAMPAIGN_COMPLETED`, and `LEAD_TAG_UPDATED`.

**Output fields**

Every event is mapped to a fixed, predictable set of columns. The nested `lead`, `campaign`, and `sender` objects are flattened to the top level with a prefix — for example `lead.profile_url` becomes `lead_profile_url` and `campaign.name` becomes `campaign_name`. Fields that only apply to certain event types (e.g. `connection_message`, `recent_messages`, `recent_inmails`, `conversation_id`) are left empty when not relevant.

Columns include `event_type`, `timestamp`, `correlation_id`, the `campaign_*`, `sender_*`, and `lead_*` fields (such as `lead_profile_url`, `lead_email_address`, `lead_first_name`, `lead_last_name`, `lead_company_name`, `lead_position`, `lead_tags`, `lead_lists`), plus the message/conversation fields for messaging events.

<Note>
  Events are unified as contact events, matched on the lead's LinkedIn profile URL and, when present, their email address.
</Note>

***

## Use cases

<AccordionGroup>
  <Accordion title="Qualified lead outreach" icon="bullseye">
    Add leads that meet your ICP criteria to targeted LinkedIn campaigns.
  </Accordion>

  <Accordion title="Multi-channel sequences" icon="share-nodes">
    Combine LinkedIn outreach with email for multi-touch campaigns.
  </Accordion>

  <Accordion title="Campaign management" icon="sliders">
    Dynamically add or stop leads based on their engagement or status changes.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Validate LinkedIn URLs** - Ensure profile URLs are valid before adding to campaigns
2. **Use custom mappings** - Pass personalization variables for better response rates
3. **Monitor campaign limits** - Respect LinkedIn's daily connection and message limits


# HTTP
Source: https://docs.getcargo.ai/integration/http

Connect to any API or webhook using the HTTP integration for custom integrations in your workflows.

## How to set up HTTP

### Authentication

The HTTP integration supports flexible header-based authentication:

1. Add the HTTP integration in Cargo
2. Configure headers for authentication:
   * **Public headers**: Visible values (Content-Type, etc.)
   * **Secret headers**: Encrypted values (API keys, tokens)

**Common authentication patterns:**

**API Key:**

```
Key: Authorization
Value: Bearer your-api-key
Type: Secret
```

**Basic Auth:**

```
Key: Authorization
Value: Basic base64(username:password)
Type: Secret
```

**Custom headers:**

```
Key: X-API-Key
Value: your-api-key
Type: Secret
```

## HTTP actions

### Call

Make HTTP requests to any API endpoint.

**Required fields:**

* **URL**: The endpoint URL (supports template expressions)
* **Method**: POST, PUT, PATCH, GET, or DELETE
* **Body format**: Form, JSON, or Text

**Optional fields:**

* **Headers**: Additional request headers (merged with connector headers)

**Body formats:**

**Form:**
Map attributes to values for form-encoded requests.

**JSON:**
Raw JSON body with template expression support.

**Text:**
Plain text body with template expression support.

**Use cases:**

* Send data to third-party APIs
* Trigger webhooks
* Integrate with any REST API
* Custom CRM integrations

### Browse

Fetch and render web page content.

**Required fields:**

* **URL**: The web page URL

**Use case:** Extract content from web pages for analysis or processing.

## HTTP data models

### Listen webhook

Receive incoming webhook data from external systems.

**Configuration:** No additional configuration required.

When configured, Cargo provides a unique webhook URL. External systems can POST data to this URL to trigger workflows.

**Use cases:**

* Receive form submissions
* Process payment notifications
* Handle CRM webhooks
* Integrate with Zapier/Make

### Fetch URL

Periodically fetch data from a URL endpoint.

**Required fields:**

* **URL**: The API endpoint that returns JSON

**Optional fields:**

* **Path**: JSON path to the results array (e.g., "results", "data.items")
* **Deduplication key**: Unique field for deduplication (default: "id")
* **Headers**: Additional request headers

**Requirements:**

* Endpoint must return JSON
* Response should be an array or contain an array at the specified path
* Results should be in reverse chronological order

**Use cases:**

* Sync data from external APIs
* Monitor RSS-like feeds
* Pull data from custom systems

## Example: Posting to a Slack-like webhook

```
URL: https://hooks.example.com/services/xxx/yyy/zzz
Method: POST
Body format: JSON
Body:
{
  "text": "New lead: {{first_name}} {{last_name}} from {{company}}",
  "channel": "#sales-alerts"
}
```

## Example: Calling a REST API

```
URL: https://api.example.com/v1/contacts
Method: POST
Headers:
  Content-Type: application/json
Body format: JSON
Body:
{
  "email": "{{email}}",
  "firstName": "{{first_name}}",
  "lastName": "{{last_name}}",
  "company": "{{company_name}}"
}
```

## Best practices

* Store sensitive credentials (API keys, tokens) as Secret headers
* Use template expressions to dynamically build URLs and bodies
* Set appropriate Content-Type headers for your request format
* Handle pagination when fetching large datasets
* Use the deduplication key to prevent duplicate processing
* Test endpoints with sample data before full deployment


# HubSpot MCP
Source: https://docs.getcargo.ai/integration/hubspot-mcp

Connect HubSpot's hosted MCP server so your AI agents can use HubSpot tools.

HubSpot MCP connects HubSpot's hosted MCP (Model Context Protocol) server to Cargo so [AI agents](/agents/tools-and-actions#mcp-servers) can call HubSpot's tools directly. It is separate from the regular [HubSpot](/integration/hubspot) CRM connection: it authorizes against HubSpot's MCP server, not the CRM API.

## How to set up HubSpot MCP

### Authentication

HubSpot MCP uses OAuth authorization:

1. Create a HubSpot MCP connector in Cargo
2. Click **Authorize HubSpot MCP**
3. Sign in to HubSpot in the popup and grant access
4. Cargo stores the resulting token and refreshes it automatically

<Note>
  **Code slugs** — integration slug: `hubspotMcp`. This integration exposes no fixed actions: its tools are discovered from HubSpot's MCP server at runtime and made available to agents.
</Note>

## HubSpot MCP tools

The connector does not define static actions. When attached to an agent as an MCP server, the agent lists the tools HubSpot's server advertises at runtime and can call any of them. See [MCP servers](/agents/tools-and-actions#mcp-servers) for how agents use MCP tools.

Related MCP integrations: [Salesforce MCP](/integration/salesforce-mcp) and [Notion MCP](/integration/notion-mcp).

## Best practices

* Use HubSpot MCP for agent tool use; keep the regular [HubSpot](/integration/hubspot) connector for workflow actions and data syncing
* Authorize with a HubSpot user whose permissions match what you want agents to be able to do
* Re-authorize the connector if HubSpot access is revoked on the HubSpot side


# Cargo app
Source: https://docs.getcargo.ai/integration/hubspot/app

Run a Cargo tool from a HubSpot workflow.

Install Cargo's HubSpot app to add **Run Cargo tool** as an action in HubSpot contact and company workflows. Connect the same HubSpot portal in Cargo first.

## Build the Cargo tool

The HubSpot action does not map fields. Cargo always sends a fixed payload from the enrolled record. The tool's **start node** must include `id` (the HubSpot record id). The other keys below are sent when present and may be declared on the start node, but they are not required for the tool to appear in the dropdown.

**Contact workflows** send:

| Start-node field | Value              |
| ---------------- | ------------------ |
| `id`             | HubSpot contact id |
| `email`          | Contact email      |
| `firstName`      | Contact first name |
| `lastName`       | Contact last name  |

**Company workflows** send:

| Start-node field | Value              |
| ---------------- | ------------------ |
| `id`             | HubSpot company id |
| `domain`         | Company domain     |
| `name`           | Company name       |

Use a contact-shaped start node for contact workflows and a company-shaped start node for company workflows. Extra HubSpot properties are not included. Only **deployed** tools whose start node includes `id` appear in the HubSpot dropdown.

## Run a Cargo tool from a HubSpot workflow

1. Deploy the tool in Cargo with the start-node fields above.
2. In HubSpot, create a contact or company workflow.
3. Add the **Run Cargo tool** action and pick the tool.

HubSpot waits until the Cargo run finishes, then receives `runUuid`, `status`, and a string `output` for later workflow steps.

Reconnect the HubSpot connector in Cargo so Professional and Enterprise portals can grant the optional `automation` scope. Without that scope, HubSpot waits until the action times out instead of receiving the run results. Free and Starter portals can still connect HubSpot; they cannot complete that callback.


# HubSpot
Source: https://docs.getcargo.ai/integration/hubspot/index

This page outlines how to use the HubSpot integration to pull and manage CRM data in Cargo.

HubSpot is an all-in-one CRM platform that helps businesses manage marketing, sales, and customer service. Cargo's native integration with HubSpot allows you to both pull data from the CRM as part of data models, and write or delete data from all CRM objects to maintain it.

## How to set up HubSpot

Cargo supports two authentication methods for HubSpot:

1. **OAuth 2** – The default method. During connection, you'll be redirected to HubSpot to authorize Cargo.
2. **Private App** – Use a HubSpot Private App access token for more granular permission control.

Once the connector is created, you can:

* **Set up a HubSpot data model** — Create data models from your HubSpot objects to trigger Plays and power model search actions.
* **Use HubSpot in workflows** — Choose **HubSpot** from the node catalog within a **Play**, **Tool**, or **Agent**.
* **Run a Cargo tool from a HubSpot workflow** — See [Cargo app](/integration/hubspot/app).

***

## HubSpot actions

<Tip>
  All HubSpot actions support Contacts, Companies, Deals, Tickets, and any
  custom objects you've created in your HubSpot account.
</Tip>

### Insert record

Insert a new record into HubSpot.

**Use cases**

* **Lead capture** – Create new contacts from various sources and channels
* **Company creation** – Add new companies from forms, events, or imports
* **Deal creation** – Create new deals to track opportunities through your pipeline

### Match records

Check if records exist in HubSpot based on matching criteria.

**Use cases**

* **Duplicate prevention** – Avoid creating duplicate records
* **Smart routing** – Route records based on existing data

<Info>
  Use **Match records** before **Insert record** to implement an upsert pattern
  for single records.
</Info>

### Find records

Find records matching the given criteria. Define multiple matching criteria—the action searches for records that match any of the provided values. Empty values are automatically skipped.

**Use cases**

* **Multi-identifier matching** – Search by domain, LinkedIn URL, or company name
* **Flexible lookups** – Find records using whichever identifiers are available
* **Data quality handling** – Provide multiple identifiers to maximize match rates

**Example configuration**

| Property                | Value                            |
| ----------------------- | -------------------------------- |
| `domain`                | `{{nodes.start.company_domain}}` |
| `linkedin_company_page` | `{{nodes.start.linkedin_url}}`   |
| `name`                  | `{{nodes.start.company_name}}`   |

<Tip>
  Empty values are automatically skipped, so you can provide all available
  identifiers without worrying about null checks.
</Tip>

### Search records

Retrieve multiple records from HubSpot based on search criteria.

**Use cases**

* **Advanced filtering** – Find records meeting specific criteria
* **Bulk operations** – Retrieve multiple records for processing inside a group node

### Update records

Update existing records in HubSpot.

**Use cases**

* **Data enrichment** – Keep record information current and accurate
* **Lifecycle management** – Update record stages, deal stages, and statuses
* **Lead scoring** – Update contact scores based on engagement signals

### Upsert records

Upsert multiple records into HubSpot (insert or update based on matching criteria).

**Use cases**

* **Bulk data operations** – Insert records in bulk while avoiding duplicates
* **Data synchronization** – Keep external systems synchronized with HubSpot

<Warning>
  Upsert operations will match on the fields you specify. Ensure your matching
  criteria is unique to avoid unintended updates.
</Warning>

### Merge records

Merge two records of the same object type into one.

**Use cases**

* **Deduplication** – Combine duplicate records into a single master record
* **Data consolidation** – Merge records when companies or contacts are identified as the same

### Delete records

Delete records from HubSpot.

**Use cases**

* **Data cleanup** – Remove outdated or incorrect records programmatically or in batches

### Count records

Count records matching specific criteria.

**Use cases**

* **Reporting** – Get counts for dashboards and metrics
* **Conditional logic** – Make workflow decisions based on record counts

### Add to list

Add a contact to a HubSpot list.

**Use cases**

* **Segmentation** – Add contacts to marketing lists based on workflow criteria
* **Campaign targeting** – Build audiences for email campaigns

### Delete from list

Remove a contact from a HubSpot list.

**Use cases**

* **List hygiene** – Remove contacts who no longer meet list criteria
* **Unsubscribe handling** – Remove contacts from specific campaign lists

### Create association

Create an association between two records in HubSpot.

**Use cases**

* **Relationship mapping** – Link contacts to companies or deals
* **Account hierarchies** – Connect parent and child companies

### Delete association

Remove an association between two records in HubSpot.

**Use cases**

* **Relationship cleanup** – Remove incorrect associations
* **Data restructuring** – Update record relationships

### Enroll to sequence

Enroll a contact in a HubSpot sequence.

**Use cases**

* **Sales outreach** – Automatically enroll leads in nurture sequences
* **Follow-up automation** – Trigger sequences based on workflow conditions

### Submit form

Submit data to a HubSpot form.

**Use cases**

* **Lead capture** – Submit form data from external sources
* **Data collection** – Capture information while respecting HubSpot form settings and workflows

### Unsubscribe contact

Unsubscribe a contact from all email subscriptions.

**Use cases**

* **GDPR compliance** – Honor unsubscribe requests
* **Preference management** – Respect contact communication preferences

***

## HubSpot data models

Cargo allows you to create data models on top of your HubSpot CRM data that can be used to trigger Plays and power model search actions.

### Creating HubSpot data models

| Field           | Description                                                                                               |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| **Name**        | Choose a descriptive name for your data model (required)                                                  |
| **Slug**        | Set a unique identifier that cannot be changed once created (required)                                    |
| **Object Type** | Select the HubSpot object type you want to model (Contacts, Companies, Deals, Tickets, or custom objects) |

### Object types available

<AccordionGroup>
  <Accordion title="Contact models" icon="user">
    **Use cases** - Handle lead and contact information - Track individual
    engagement and communication history - Manage contact lifecycle stages and
    lead scoring
  </Accordion>

  <Accordion title="Company models" icon="building">
    **Use cases** - Manage company records with domains, industry, and size
    information - Track company relationships and hierarchies - Monitor account
    engagement and lifecycle stages
  </Accordion>

  <Accordion title="Deal models" icon="handshake">
    **Use cases** - Track opportunities, pipeline stages, and deal progression -
    Monitor deal velocity, conversion rates, and forecasting - Analyze win/loss
    patterns and sales performance
  </Accordion>

  <Accordion title="Ticket models" icon="ticket">
    **Use cases** - Track customer support requests and issues - Monitor ticket
    resolution times and SLA compliance - Analyze support patterns and team
    performance
  </Accordion>
</AccordionGroup>

<Tip>
  You can also model any **custom objects** you've created in HubSpot, giving
  you full flexibility to work with your unique data structures.
</Tip>


# Hunter
Source: https://docs.getcargo.ai/integration/hunter

This page outlines how to use the Hunter integration for email finding and verification in Cargo.

Hunter is an email outreach platform that helps you find and verify professional email addresses. Cargo's native integration with Hunter allows you to find emails, verify addresses, and search company domains directly from your workflows.

## How to set up Hunter

You can use Hunter in two ways:

1. **Cargo credits** – Use Hunter through Cargo's managed integration
2. **Your own API key** – Connect your Hunter account

### Connection details

| Field       | Description         |
| ----------- | ------------------- |
| **API Key** | Your Hunter API key |

<Tip>Find your API key in Hunter under **API**.</Tip>

***

## Hunter actions

### Find email

Find a person's professional email address.

**Use cases**

* **Prospecting** – Find email addresses for target contacts
* **Data completion** – Fill in missing email addresses
* **Outreach preparation** – Build email lists for campaigns

**Configuration**

| Field          | Description                      |
| -------------- | -------------------------------- |
| **First name** | Person's first name              |
| **Last name**  | Person's last name               |
| **Full name**  | Person's full name (alternative) |
| **Domain**     | Company domain                   |
| **Company**    | Company name                     |

<Info>Provide either first/last name or full name along with domain or company for best results.</Info>

**Credit cost:** 0.5 credits per lookup

### Verify email

Verify if an email address is valid and deliverable.

**Use cases**

* **List hygiene** – Clean email lists before campaigns
* **Bounce prevention** – Verify before sending
* **Data quality** – Ensure email accuracy

**Configuration**

| Field     | Description             |
| --------- | ----------------------- |
| **Email** | Email address to verify |

**Credit cost:** 1 credit per verification

### Enrich person

Get detailed information about a person from their email.

**Use cases**

* **Contact enrichment** – Enrich contacts with professional data
* **Lead qualification** – Gather context for scoring

**Configuration**

| Field     | Description             |
| --------- | ----------------------- |
| **Email** | Email address to enrich |

**Credit cost:** 1 credit per enrichment

### Search domain

Find all email addresses associated with a company domain.

**Use cases**

* **Account prospecting** – Find contacts at target companies
* **Organizational mapping** – Understand company structure
* **Lead generation** – Build prospect lists

**Configuration**

| Field               | Description                      |
| ------------------- | -------------------------------- |
| **Domain**          | Company domain to search         |
| **Type**            | All, Personal, or Generic emails |
| **Seniorities**     | Junior, Senior, Executive        |
| **Departments**     | IT, Sales, Marketing, HR, etc.   |
| **Required fields** | Fullname, Position, Phone number |
| **Limit**           | Maximum records to return        |

**Credit cost:** 1 credit per search


# Icypeas
Source: https://docs.getcargo.ai/integration/icypeas

Connect Icypeas to find and verify email addresses in your workflows.

## How to set up Icypeas

### Authentication

Icypeas uses API key authentication:

1. Sign up at [icypeas.com](https://icypeas.com)
2. Navigate to your API settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## Icypeas actions

### Find email

Find a person's email address using their name and company.

**Required fields:**

* **First name**: Person's first name
* **Last name**: Person's last name
* **Company name/domain**: Company domain or name

**Credits:** 0.1 credits per request

**Use case:** Discover professional email addresses for prospecting.

### Verify email

Check if an email address is valid and deliverable.

**Required fields:**

* **Email address**: The email to verify

**Credits:** 0.01 credits per request

**Use case:** Very affordable email verification for list cleaning.

### Scan domain

Discover all role-based email addresses at a domain.

**Required fields:**

* **Company name/domain**: Domain or company name to scan

**Returns:** Role-based emails like:

* [contact@company.com](mailto:contact@company.com)
* [info@company.com](mailto:info@company.com)
* [admin@company.com](mailto:admin@company.com)
* [support@company.com](mailto:support@company.com)

**Credits:** 0.1 credits per request

**Use case:** Find generic company emails for initial outreach.

## Credits summary

| Action       | Credits |
| ------------ | ------- |
| Find email   | 0.1     |
| Verify email | 0.01    |
| Scan domain  | 0.1     |

Icypeas offers very competitive pricing, especially for email verification at 0.01 credits per check.

## Retry behavior

Icypeas actions include automatic retry logic with exponential backoff to handle rate limits gracefully.

## Rate limits

Icypeas API has a rate limit of 30 requests per minute. Cargo handles rate limiting automatically.

## Best practices

* Use domain scanning to find company-wide contact points
* Verify emails before outreach (very affordable at 0.01 credits)
* Provide company domain rather than name for better accuracy
* Combine with other enrichment sources for complete coverage


# Instantly
Source: https://docs.getcargo.ai/integration/instantly

Connect Instantly to manage cold email campaigns and leads in your workflows.

## How to set up Instantly

### Authentication

Instantly uses API key authentication:

1. Log in to your Instantly account
2. Navigate to **Settings** → **Integrations** → **API**
3. Generate or copy your API key
4. Paste the API key in Cargo when connecting

> **Note:** This integration is for Instantly Legacy. For newer Instantly accounts, use the Instantly V2 integration.

## Instantly actions

### Search

Search for leads or accounts in Instantly.

**Configuration:**

* **Object type**: Choose between Lead or Account

**For Leads:**

* **Email**: The lead's email address (required)
* **Campaign ID**: Filter by specific campaign (optional)

**Use case:** Look up existing leads before adding them to campaigns to avoid duplicates.

### Write

Perform actions on leads in Instantly.

**Required fields:**

* **Object type**: Currently supports Lead
* **Action**: Choose from Create, Update, Remove, Block, or Unblock
* **Email**: The lead's email address

**For Create/Update actions:**

* **Campaign ID**: The campaign to add the lead to (required)
* **Status**: Lead status
* **Skip if in workspace**: Prevent duplicates if lead exists
* **Mappings**: Map standard variables (First name, Last name, Company, etc.)
* **Custom mappings**: Map custom variables for personalization

**For Remove action:**

* **Campaign ID**: The campaign to remove from
* **Delete all from company**: Remove all leads from the same company

**Use cases:**

**Creating leads:**

* Add qualified leads from your CRM to cold email campaigns
* Automatically enroll leads based on scoring or segmentation

**Updating leads:**

* Update lead status based on engagement
* Sync latest contact information

**Blocking leads:**

* Block leads who have unsubscribed
* Prevent outreach to competitors or existing customers

## Variable mappings

When creating or updating leads, you can map these standard variables:

| Variable     | Description                       |
| ------------ | --------------------------------- |
| First name   | Contact's first name              |
| Last name    | Contact's last name               |
| Company name | Company name                      |
| Phone        | Phone number                      |
| Website      | Company website                   |
| Custom 1-5   | Custom fields for personalization |

## Rate limits

Instantly has a rate limit of 5 requests per second. Cargo automatically handles rate limiting and retries to ensure reliable delivery.


# Instantly
Source: https://docs.getcargo.ai/integration/instantly-v2

Connect Instantly to manage leads and cold email campaigns in your workflows.

## How to set up Instantly

### Authentication

Instantly uses API key authentication:

1. Log in to your Instantly account
2. Navigate to **Settings** → **API**
3. Generate or copy your API key
4. Paste the API key in Cargo when connecting

## Instantly actions

### Create lead

Add a new lead to an Instantly campaign.

**Required fields:**

* **Email**: Lead's email address

**Optional fields:**

* **Campaign**: Select campaign to add lead to
* **List**: Select lead list to add to
* **Assigned to**: Assign to team member

**Standard fields:**

| Field           | Description          |
| --------------- | -------------------- |
| first\_name     | Lead's first name    |
| last\_name      | Lead's last name     |
| company\_name   | Company name         |
| personalization | Personalization text |
| phone           | Phone number         |
| website         | Company website      |

**Custom variables:** Add any custom fields for email personalization.

**Duplicate handling:**

* **Skip if in workspace**: Prevent adding duplicates in workspace
* **Skip if in campaign**: Prevent adding to same campaign twice
* **Skip if in list**: Prevent adding to same list twice

### Update lead

Modify an existing lead's information.

**Required fields:**

* **Lead ID**: The lead's unique identifier

**Optional fields:** Same as create lead (all standard and custom fields).

### Delete lead

Remove a lead from Instantly.

**Required fields:**

* **Lead ID**: The lead's unique identifier

## Instantly data models

### Fetch leads

Pull all leads from Instantly into Cargo.

**Features:**

* Syncs all leads from your workspace
* 30-minute minimum sync interval
* Unifies contacts by email

### Listen events

Receive real-time events from Instantly.

**Event types:**

* Email sent
* Email opened
* Link clicked
* Reply received
* Bounced
* Unsubscribed

**Features:**

* Auto-ingests events as they occur
* Real-time webhook processing

## Rate limits

Instantly API has a rate limit of 10 requests per second. Cargo handles rate limiting automatically.

## Best practices

* Use custom variables for personalized outreach
* Enable duplicate skip options to avoid re-adding leads
* Leverage events for real-time engagement tracking
* Assign leads to team members for follow-up
* Use lead lists for organization


# Intercom
Source: https://docs.getcargo.ai/integration/intercom

This page outlines how to use the Intercom integration to manage customer support contacts in Cargo.

Intercom is a leading customer communication platform that helps businesses build stronger relationships through messaging, live chat, and customer support. Cargo's native integration with Intercom allows you to create, update, and manage contacts directly from your workflows.

## How to set up Intercom

To connect Intercom, you'll need an access token from your Intercom account.

### Connection details

| Field            | Description                            |
| ---------------- | -------------------------------------- |
| **Access token** | Your Intercom Private App access token |

<Tip>
  You can generate an access token by creating a Private App in your Intercom
  Developer Hub. Make sure to grant the necessary permissions for contacts.
</Tip>

Once the connector is created, you can:

* **Use Intercom in workflows** — Choose **Intercom** from the node catalog within a **Play**, **Tool**, or **Agent**.

***

## Intercom actions

### Create Contact

Create a new contact in Intercom.

**Use cases**

* **Lead capture** – Create contacts from inbound leads, form submissions, or enrichment workflows
* **Customer onboarding** – Add new customers to Intercom for proactive support
* **Data sync** – Keep Intercom contacts in sync with other systems

**Configuration**

| Field               | Description                           |
| ------------------- | ------------------------------------- |
| **Mappings**        | Map standard contact fields to values |
| **Custom Mappings** | Map custom attributes to values       |

### Upsert Contact

Create a new contact or update an existing one based on a matching field.

**Use cases**

* **Avoid duplicates** – Ensure contacts aren't duplicated when syncing data
* **Data enrichment** – Update existing contacts with new information
* **Idempotent operations** – Safely retry operations without creating duplicates

**Configuration**

| Field                            | Description                                           |
| -------------------------------- | ----------------------------------------------------- |
| **Intercom Matching Field Name** | Field to match on: Email, External ID, or Intercom ID |
| **Matching Value**               | The value to match against                            |
| **Mappings**                     | Map standard contact fields to values                 |
| **Custom Mappings**              | Map custom attributes to values                       |

<Info>
  When upserting, Intercom will first search for an existing contact matching
  your criteria. If found, it updates the contact; otherwise, it creates a new
  one.
</Info>

### Update Contact

Update an existing contact in Intercom.

**Use cases**

* **Data enrichment** – Update contact information with enriched data
* **Lifecycle updates** – Update contact attributes based on user actions
* **Sync changes** – Push updates from your CRM or other systems to Intercom

**Configuration**

| Field                            | Description                                           |
| -------------------------------- | ----------------------------------------------------- |
| **Intercom Matching Field Name** | Field to match on: Email, External ID, or Intercom ID |
| **Matching Value**               | The value to match against                            |
| **Mappings**                     | Map standard contact fields to values                 |
| **Custom Mappings**              | Map custom attributes to values                       |

### Delete Contact

Delete a contact from Intercom.

**Use cases**

* **GDPR compliance** – Remove contacts upon data deletion requests
* **Data cleanup** – Remove invalid or outdated contacts
* **Lifecycle management** – Remove contacts that no longer meet criteria

**Configuration**

| Field                            | Description                                           |
| -------------------------------- | ----------------------------------------------------- |
| **Intercom Matching Field Name** | Field to match on: Email, External ID, or Intercom ID |
| **Matching Value**               | The value to match against                            |

<Warning>
  Deleting a contact is permanent and cannot be undone. Make sure you have the
  correct matching criteria before executing this action.
</Warning>

***

## Best practices

### Contact matching

When updating or deleting contacts, choose your matching field carefully:

* **Email** – Best for most use cases; matches contacts by email address
* **External ID** – Use when you have a consistent external identifier from your systems
* **Intercom ID** – Use when you've previously retrieved the contact and stored its Intercom ID

### Custom attributes

Intercom supports custom attributes on contacts. Use the **Custom Mappings** field to set values for any custom attributes you've defined in your Intercom workspace.

<Tip>
  Define your custom attributes in Intercom first, then use the autocomplete in
  Cargo to select them when configuring your mappings.
</Tip>


# Jira
Source: https://docs.getcargo.ai/integration/jira

This page outlines how to use the Jira integration for issue tracking in Cargo.

Jira is a project management and issue tracking platform by Atlassian, widely used for agile software development and team collaboration. Cargo's native integration with Jira allows you to create and retrieve issues directly from your workflows.

## How to set up Jira

To connect Jira, you'll need your domain, email, and an API key.

### Connection details

| Field           | Description                                                         |
| --------------- | ------------------------------------------------------------------- |
| **Jira Domain** | Your Jira subdomain (e.g., `mycompany` for mycompany.atlassian.net) |
| **User Email**  | Your Jira user email address                                        |
| **API Key**     | Your Jira API token                                                 |

<Tip>Generate an API token in Atlassian under **Account Settings → Security → API tokens**.</Tip>

Once the connector is created, you can:

* **Use Jira in workflows** — Choose **Jira** from the node catalog within a **Play**, **Tool**, or **Agent**.

***

## Jira actions

### Create Issue

Create a new issue in a Jira project.

**Use cases**

* **Bug tracking** – Create issues from customer support tickets or error alerts
* **Feature requests** – Turn qualified leads into product feature requests
* **Task automation** – Create tasks based on workflow triggers

**Configuration**

| Field             | Description                        |
| ----------------- | ---------------------------------- |
| **Project Key**   | The project to create the issue in |
| **Issue Type**    | Bug, Task, Story, Epic, etc.       |
| **Summary**       | Issue title/summary                |
| **Description**   | Detailed description               |
| **Custom Fields** | Additional project-specific fields |

<Info>Custom fields vary by project and issue type. Cargo automatically loads available fields based on your selection.</Info>

### Get Issue

Retrieve an existing issue by its ID or key.

**Use cases**

* **Status lookup** – Check issue status before taking action
* **Data enrichment** – Pull issue details into workflows
* **Conditional routing** – Route based on issue properties

**Configuration**

| Field               | Description                           |
| ------------------- | ------------------------------------- |
| **Issue ID or Key** | The issue identifier (e.g., PROJ-123) |


# Kaspr
Source: https://docs.getcargo.ai/integration/kaspr

Connect Kaspr to enrich LinkedIn profiles with emails and phone numbers in your workflows.

## How to set up Kaspr

### Authentication

Kaspr uses API key authentication:

1. Sign up at [kaspr.io](https://kaspr.io)
2. Navigate to your API settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## Kaspr actions

### Enrich LinkedIn profile

Get work email, direct email, and phone number from a LinkedIn profile.

**Required fields:**

* **LinkedIn profile ID or URL**: Person's LinkedIn profile identifier or full URL
* **Profile full name**: Person's full name (improves matching accuracy)

**Data options:**

* **Data to include**: Select which data types to return
  * Phone
  * Direct email
  * Work email

* **Data to require**: Only return results with these fields present
  * Phone
  * Direct email
  * Work email

**Use case:** Convert LinkedIn profiles to actionable contact data.

## Response data

Kaspr enrichment returns:

| Field       | Description                   |
| ----------- | ----------------------------- |
| phone       | Phone number(s)               |
| directEmail | Personal/direct email address |
| workEmail   | Professional work email       |
| firstName   | First name                    |
| lastName    | Last name                     |
| linkedin    | LinkedIn profile URL          |

## Best practices

* Always include full name for better matching
* Use "data to require" to ensure results have needed fields
* Select only the data types you need
* Combine with verification for highest quality
* Cache results to avoid redundant enrichment


# Kitt
Source: https://docs.getcargo.ai/integration/kitt

Connect Kitt to verify email addresses in your workflows.

## How to set up Kitt

### Authentication

Kitt uses API key authentication:

1. Log in to your Kitt dashboard
2. Copy your API key
3. Paste the API key in Cargo when connecting

<Note>
  **Code slugs** — integration slug: `kitt` · action: `verifyEmail`. In a [workflow](/workflows/overview), declare the connector in `uses` and call `uses.<key>.verifyEmail(...)`.
</Note>

## Kitt actions

### Verify email

Verify an email address in real time and get its validity, SMTP status, and a reason when invalid.

**Required fields:**

* **Email**: The email address to verify

**Credits:** 0.05 credits per request

**Use case:** Clean prospect lists before sequencing to protect sender reputation and reduce bounces.

## Best practices

* Verify emails right after enrichment, before they enter any outreach sequence
* Branch workflows on the returned validity and reason to route risky addresses separately
* Cache results to avoid re-verifying the same address repeatedly
* High-volume runs are handled for you: Cargo spreads requests within the connector's rate limit (100 per second)


# LeadMagic
Source: https://docs.getcargo.ai/integration/lead-magic

Connect LeadMagic to enrich profiles and find email addresses in your workflows.

## How to set up LeadMagic

### Authentication

LeadMagic uses API key authentication:

1. Sign up at [leadmagic.io](https://leadmagic.io)
2. Navigate to your API settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## LeadMagic actions

### Enrich profile

Get comprehensive profile data from an email address.

**Required fields:**

* **Email**: Person's email address

**Optional fields:**

* **Is personal email**: Indicate if this is a personal email

**Credits:** 3 credits per request

**Returns:**

* Full name
* Job title
* Company information
* Social profiles
* Location data

**Use case:** Enrich existing email contacts with additional profile data.

### Find email

Find a person's email address using their name and company.

**Required fields:**

* **First name**: Person's first name
* **Last name**: Person's last name

**Optional fields:**

* **Domain**: Company domain (recommended)
* **Company name**: Company name

**Credits:** 0.5 credits per request

**Use case:** Discover professional email addresses for prospecting.

## Credits summary

| Action         | Credits |
| -------------- | ------- |
| Find email     | 0.5     |
| Enrich profile | 3       |

## Rate limits

LeadMagic API has a rate limit of 300 requests per minute. Cargo handles rate limiting automatically.

## Best practices

* Provide company domain for better email matching
* Use enrichment to fill gaps in contact data
* Cache results to optimize credit usage
* Combine find email + enrich for complete profiles


# Lemlist
Source: https://docs.getcargo.ai/integration/lemlist

This page outlines how to use the Lemlist integration for sales outreach and email campaigns in Cargo.

Lemlist is a sales engagement platform that helps teams send personalized cold emails at scale with automated follow-ups and advanced personalization. Cargo's native integration with Lemlist allows you to manage leads, campaigns, and email activities directly from your workflows.

## How to set up Lemlist

To connect Lemlist, you'll need an API key from your Lemlist account.

### Connection details

| Field       | Description          |
| ----------- | -------------------- |
| **API Key** | Your Lemlist API key |

<Tip>Find your API key in Lemlist under **Settings → Integrations → API**.</Tip>

Once the connector is created, you can:

* **Set up Lemlist data models** — Create data models from your Lemlist leads and activities to trigger Plays.
* **Use Lemlist in workflows** — Choose **Lemlist** from the node catalog within a **Play**, **Tool**, or **Agent**.

***

## Lemlist actions

### Create Lead

Create a new lead in a Lemlist campaign.

**Use cases**

* **Campaign enrollment** – Add qualified leads to outreach campaigns
* **List building** – Push leads from various sources to Lemlist
* **Multi-channel sequences** – Enroll leads in email sequences

**Configuration**

| Field        | Description                               |
| ------------ | ----------------------------------------- |
| **Campaign** | Select the campaign to add the lead to    |
| **Email**    | The lead's email address                  |
| **Mappings** | Map additional lead attributes            |
| **Options**  | Additional processing options (see below) |

**Available options**

| Option                  | Description                                    |
| ----------------------- | ---------------------------------------------- |
| **Deduplicate**         | Check if email exists in other campaigns first |
| **Find email**          | Use Lemlist to find verified email             |
| **LinkedIn enrichment** | Run LinkedIn enrichment on the lead            |
| **Verify email**        | Verify the existing email address              |

<Info>
  When creating leads with the **Deduplicate** option, Lemlist will check all
  campaigns to prevent adding the same email twice.
</Info>

### Update Lead

Update an existing lead in a campaign.

**Use cases**

* **Data enrichment** – Update leads with enriched data
* **Status updates** – Update lead information based on external events
* **Field updates** – Sync lead data from other systems

**Configuration**

| Field        | Description                             |
| ------------ | --------------------------------------- |
| **Campaign** | Select the campaign containing the lead |
| **Email**    | The lead's email address to match       |
| **Mappings** | Map lead attributes to update           |

### Upsert Lead

Create a new lead or update an existing one.

**Use cases**

* **Data sync** – Sync leads from your CRM without duplicates
* **Idempotent operations** – Safely retry lead creation
* **Continuous enrollment** – Keep leads updated as data changes

**Configuration**

| Field        | Description                |
| ------------ | -------------------------- |
| **Campaign** | Select the target campaign |
| **Email**    | The lead's email address   |
| **Mappings** | Map lead attributes        |

### Upsert Contact

Create or update a contact in the Lemlist CRM without enrolling them in a campaign.

**Use cases**

* **CRM sync** – Push enriched contacts into Lemlist before outreach
* **Data enrichment** – Update contact fields from external sources
* **Company linking** – Associate contacts with existing companies

**Configuration**

| Field                      | Description                                                         |
| -------------------------- | ------------------------------------------------------------------- |
| **Contact ID**             | Update an existing contact by ID (optional)                         |
| **Email**                  | Primary identifier for create/update (optional)                     |
| **LinkedIn URL**           | Alternative identifier (optional)                                   |
| **LinkedIn Sales Nav URL** | Alternative identifier (optional)                                   |
| **Contact owner**          | Team member to assign as owner (optional)                           |
| **Company ID**             | Link to an existing company by ID (optional)                        |
| **Company domain**         | Link to a company by domain (optional)                              |
| **Company LinkedIn URL**   | Link to a company by LinkedIn URL (optional)                        |
| **Mappings**               | Map additional contact attributes (e.g. firstName, lastName, phone) |

<Info>
  At least one of **Contact ID**, **Email**, **LinkedIn URL**, or **LinkedIn
  Sales Nav URL** is required. Contacts are separate from campaign leads — use
  **Create Lead** when you want to enroll someone in a sequence.
</Info>

### Upsert Company

Create or update a company in the Lemlist CRM.

**Use cases**

* **Account sync** – Keep company records up to date from your CRM or enrichment tools
* **Pre-outreach setup** – Create companies before syncing contacts

**Configuration**

| Field                      | Description                                                       |
| -------------------------- | ----------------------------------------------------------------- |
| **Company ID**             | Update an existing company by ID (optional)                       |
| **Name**                   | Company name (required when creating without Company ID)          |
| **Domain**                 | Company website domain (required when creating without ID)        |
| **LinkedIn URL**           | Alternative identifier (optional)                                 |
| **LinkedIn Sales Nav URL** | Alternative identifier (optional)                                 |
| **Company owner**          | Team member to assign as owner (optional)                         |
| **Mappings**               | Map additional company attributes (e.g. industry, location, size) |

### Get Contact

Retrieve contact information by ID or email.

**Use cases**

* **Contact lookup** – Fetch contact data for workflow conditions
* **Pre-upsert check** – Verify a contact exists before syncing

**Configuration**

| Field  | Description                 |
| ------ | --------------------------- |
| **ID** | Contact ID or email address |

### Get Company

Retrieve company information by ID or domain.

**Use cases**

* **Account lookup** – Fetch company data for workflow conditions
* **Pre-upsert check** – Verify a company exists before syncing

**Configuration**

| Field  | Description          |
| ------ | -------------------- |
| **ID** | Company ID or domain |

### Delete Lead

Remove a lead from a campaign.

**Use cases**

* **Campaign cleanup** – Remove invalid leads
* **Unsubscribe handling** – Remove leads who opted out
* **Lead management** – Remove leads that no longer qualify

**Configuration**

| Field        | Description                             |
| ------------ | --------------------------------------- |
| **Campaign** | Select the campaign containing the lead |
| **Email**    | The lead's email address to remove      |

### Get Lead

Retrieve lead information by ID or email.

**Use cases**

* **Lead lookup** – Fetch lead data for workflow conditions
* **Status check** – Check lead status before taking action

**Configuration**

| Field  | Description              |
| ------ | ------------------------ |
| **ID** | Lead ID or email address |

### Get Campaign

Retrieve campaign information by ID.

**Configuration**

| Field  | Description |
| ------ | ----------- |
| **ID** | Campaign ID |

### Unsubscribe Lead from Campaign

Remove a lead from a specific campaign's sequence.

**Use cases**

* **Opt-out handling** – Stop sequences for specific campaigns
* **Campaign management** – Remove leads from specific outreach

**Configuration**

| Field        | Description              |
| ------------ | ------------------------ |
| **Campaign** | Select the campaign      |
| **Email**    | The lead's email address |

### Add unsubscribe email

Add an email to the global unsubscribe list.

**Use cases**

* **Global opt-out** – Prevent all future emails to an address
* **GDPR compliance** – Honor unsubscribe requests

**Configuration**

| Field     | Description                      |
| --------- | -------------------------------- |
| **Email** | The email address to unsubscribe |

<Warning>
  Adding an email to the unsubscribe list will prevent it from receiving emails
  across all campaigns.
</Warning>

### Delete unsubscribe email

Remove an email from the global unsubscribe list.

**Use cases**

* **Re-subscription** – Allow a previously unsubscribed email to receive emails
* **Error correction** – Fix accidental unsubscribes

**Configuration**

| Field     | Description                                  |
| --------- | -------------------------------------------- |
| **Email** | The email address to remove from unsubscribe |

***

## Lemlist data models

Cargo allows you to create data models on top of your Lemlist data that can be used to trigger Plays and power workflows.

### Available extractors

<AccordionGroup>
  <Accordion title="Fetch leads" icon="users">
    Pull lead records from Lemlist with incremental sync support. **Use cases**

    * Build data models from your Lemlist leads - Trigger workflows when leads
      are added or updated - Sync lead data back to your CRM
  </Accordion>

  <Accordion title="Fetch campaigns" icon="paper-plane">
    Pull campaign records from Lemlist. **Use cases** - Track campaign status
    and settings - Monitor campaign performance
  </Accordion>

  <Accordion title="Fetch activities" icon="chart-line">
    Pull activity events from Lemlist including opens, clicks, and replies.
    **Use cases** - Track email engagement - Trigger workflows on email opens or
    replies - Monitor campaign performance
  </Accordion>

  <Accordion title="Fetch unsubscribes" icon="ban">
    Pull the global unsubscribe list. **Use cases** - Sync unsubscribes to other
    systems - Maintain compliance records
  </Accordion>
</AccordionGroup>


# LaGrowthMachine
Source: https://docs.getcargo.ai/integration/lgm

Connect LaGrowthMachine to manage multi-channel sales outreach campaigns in your workflows.

## How to set up LaGrowthMachine

### Authentication

LaGrowthMachine uses API key authentication:

1. Log in to your LaGrowthMachine account
2. Navigate to **Settings** → **API**
3. Generate or copy your API key
4. Paste the API key in Cargo when connecting

## LaGrowthMachine actions

### Get Lead

Retrieve lead information by applying filters.

**Search fields (provide one or more):**

* **Lead ID**: LaGrowthMachine lead ID
* **First name**: Person's first name
* **Last name**: Person's last name
* **Company name**: Company name
* **Company URL**: Company website
* **Email**: Email address
* **LinkedIn URL**: LinkedIn profile URL

**Use case:** Look up existing leads before creating duplicates.

### Create Lead

Add a new lead to a LaGrowthMachine audience.

**Required fields:**

* **Audience**: Select the target audience

**Lead mappings (provide required combination):**

You must provide one of these combinations:

* Professional email OR Personal email
* LinkedIn URL
* Twitter handle
* First name + Last name + (Company URL or Company Name)

**Available fields:**

| Field               | Description          |
| ------------------- | -------------------- |
| firstname           | First name           |
| lastname            | Last name            |
| gender              | Gender               |
| bio                 | Biography            |
| companyName         | Company name         |
| companyUrl          | Company website      |
| jobTitle            | Job title            |
| profilePicture      | Profile picture URL  |
| linkedinUrl         | LinkedIn profile URL |
| twitter             | Twitter handle       |
| proEmail            | Professional email   |
| persoEmail          | Personal email       |
| industry            | Industry             |
| phone               | Phone number         |
| location            | Location             |
| crm\_id             | CRM identifier       |
| customAttribute1-10 | Custom attributes    |

**Use case:** Automatically add qualified leads to outreach campaigns.

### Remove Lead from Audience

Remove a lead from a specific audience.

**Required fields:**

* **Matching property name**: How to identify the lead (email, LinkedIn URL, or CRM ID)
* **Matching value**: The value to match
* **Audience**: The audience to remove from

**Use case:** Remove leads who have converted or requested no contact.

### Update Lead Status

Change the status of a lead in LaGrowthMachine.

**Required fields:**

* **Matching property name**: How to identify the lead
* **Matching value**: The value to match
* **Status**: New status

**Available statuses:**

| Status       | Description                |
| ------------ | -------------------------- |
| PAUSED       | Temporarily pause outreach |
| RESUME       | Resume paused outreach     |
| STOPPED      | Permanently stop outreach  |
| CONVERTED    | Mark as converted          |
| SUBSCRIBED   | Mark as subscribed         |
| UNSUBSCRIBED | Mark as unsubscribed       |

## Best practices

* Use CRM ID mapping for bidirectional sync
* Include as many lead fields as possible for personalization
* Remove leads promptly when they convert or opt out
* Use custom attributes for personalization variables
* Set up audiences aligned with your sales segments
* Pause leads when they show engagement before conversion

## Integration benefits

* **Multi-channel outreach**: LinkedIn, email, Twitter from one platform
* **Personalization**: Use custom attributes for dynamic content
* **CRM sync**: Keep systems aligned with crm\_id
* **Status management**: Control outreach lifecycle programmatically


# LinkedIn
Source: https://docs.getcargo.ai/integration/linkedin

This page outlines how to use the LinkedIn integration for social selling, enrichment, and automation in Cargo.

LinkedIn is the world's largest professional network, connecting professionals and businesses worldwide. Cargo's native integration with LinkedIn allows you to enrich profiles and companies, search for posts and jobs, and automate social selling activities directly from your workflows.

## How to set up LinkedIn

LinkedIn is available as a Cargo-managed integration. No API keys or OAuth setup required—simply select LinkedIn from the node catalog and start using it in your workflows.

<Info>
  LinkedIn actions consume Cargo credits. Credit costs vary by action type.
</Info>

Once connected, you can:

* **Use LinkedIn in workflows** — Choose **LinkedIn** from the node catalog within a **Play**, **Tool**, or **Agent**.
* **Fetch LinkedIn data** — Create data models from LinkedIn searches to trigger Plays.

***

## LinkedIn enrichment actions

### Enrich Profile

Retrieve detailed information about a LinkedIn profile.

**Use cases**

* **Contact enrichment** – Enrich leads with LinkedIn profile data
* **Lead qualification** – Gather professional context for scoring
* **Personalization** – Use profile data to personalize outreach

**Configuration**

| Field            | Description                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| **LinkedIn URL** | The LinkedIn profile URL (e.g., [https://linkedin.com/in/auree](https://linkedin.com/in/auree)) |

**Credit cost:** 0.25 credits per enrichment

### Enrich Profile From Name

Find and enrich a LinkedIn profile using name and company.

**Use cases**

* **Lead discovery** – Find LinkedIn profiles from CRM contact data
* **Data enrichment** – Enrich contacts when you only have name and company

**Configuration**

| Field            | Description             |
| ---------------- | ----------------------- |
| **Name**         | Full name of the person |
| **Company name** | Current company name    |

**Credit cost:** 0.5 credits per enrichment

### Enrich Company

Retrieve detailed information about a LinkedIn company page.

**Use cases**

* **Company enrichment** – Gather company data from LinkedIn
* **Account research** – Understand target accounts better
* **Lead scoring** – Use company data for ICP matching

**Configuration**

| Field            | Description                                                                                                     |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| **LinkedIn URL** | The LinkedIn company URL (e.g., [https://linkedin.com/company/linkedin](https://linkedin.com/company/linkedin)) |

**Credit cost:** 0.25 credits per enrichment

### Enrich Company From Domain

Find and enrich a LinkedIn company page using the company domain.

**Use cases**

* **Account enrichment** – Enrich companies when you only have their domain
* **Data completion** – Fill in LinkedIn company data from website URLs

**Configuration**

| Field      | Description                         |
| ---------- | ----------------------------------- |
| **Domain** | Company domain (e.g., linkedin.com) |

**Credit cost:** 0.5 credits per enrichment

### Enrich Job

Retrieve information about a LinkedIn job posting.

**Configuration**

| Field            | Description                                                                                                           |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| **LinkedIn URL** | The LinkedIn job URL (e.g., [https://linkedin.com/jobs/view/3766410207/](https://linkedin.com/jobs/view/3766410207/)) |

**Credit cost:** 0.25 credits per enrichment

### Find Custom Headcount

Count employees at a company matching specific criteria.

**Use cases**

* **ICP scoring** – Score companies based on department sizes
* **Market research** – Understand company structure
* **Territory planning** – Identify companies with specific team compositions

**Configuration**

| Field                    | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| **Company LinkedIn URL** | The LinkedIn company page URL                          |
| **Keywords**             | Boolean search keywords (e.g., "Sales" OR "Marketing") |
| **Include subsidiaries** | Include employees from subsidiary companies            |

**Credit cost:** 0.25 credits per search

***

## LinkedIn search actions

### Search Posts

Search for LinkedIn posts matching specific criteria.

**Use cases**

* **Social listening** – Monitor mentions of your brand or competitors
* **Content discovery** – Find relevant content for engagement
* **Signal detection** – Identify buying signals from posts

**Configuration**

| Field               | Description                          |
| ------------------- | ------------------------------------ |
| **Search keywords** | Keywords to search for               |
| **Sort by**         | Top match or Latest                  |
| **Date posted**     | Filter by posting date               |
| **Content type**    | All, Videos, Images, Job posts, etc. |
| **From members**    | Filter by specific member URNs       |
| **From companies**  | Filter by specific company IDs       |
| **Author industry** | Filter by author's industry          |

**Credit cost:** 0.25 credits per search

### Search Jobs

Search for LinkedIn job postings.

**Use cases**

* **Hiring signals** – Identify companies actively hiring
* **Competitive intelligence** – Monitor competitor hiring
* **Job board aggregation** – Pull job listings for your platform

**Configuration**

| Field                 | Description                                    |
| --------------------- | ---------------------------------------------- |
| **Keywords**          | Job title or skill keywords                    |
| **Geo codes**         | Location filters                               |
| **Date posted**       | Any time, Past month, Past week, Past 24 hours |
| **Experience levels** | Filter by seniority                            |
| **Job types**         | Full-time, Part-time, Contract, etc.           |
| **Onsite/Remote**     | Work location preference                       |

**Credit cost:** 0.5 credits per search

### Search Post Comments

Retrieve comments on a LinkedIn post.

**Use cases**

* **Engagement mining** – Find engaged prospects from post comments
* **Sentiment analysis** – Understand reactions to content
* **Lead generation** – Identify interested parties from comments

**Configuration**

| Field                | Description                  |
| -------------------- | ---------------------------- |
| **LinkedIn Post ID** | The post URN or ID           |
| **Sort by**          | Most recent or Most relevant |

**Credit cost:** 0.5 credits per search

### Search Post Reactions

Retrieve reactions on a LinkedIn post.

**Use cases**

* **Engagement analysis** – Understand who's engaging with content
* **Lead discovery** – Find prospects engaging with relevant posts
* **Influencer mapping** – Identify engaged audience members

**Configuration**

| Field                | Description                                        |
| -------------------- | -------------------------------------------------- |
| **LinkedIn Post ID** | The post URN or ID                                 |
| **Type**             | All, Like, Empathy, Appreciation, Interest, Praise |

**Credit cost:** 0.5 credits per search

***

## LinkedIn social selling actions

<Warning>
  Social selling actions require LinkedIn users to be connected to Cargo.
  These actions are performed on behalf of the connected user.
</Warning>

### Connect Profile

Send a connection request to a LinkedIn profile.

**Configuration**

| Field                    | Description                 |
| ------------------------ | --------------------------- |
| **LinkedIn Profile URL** | The profile to connect with |
| **Message**              | Optional connection message |
| **LinkedIn Users**       | Users to perform the action |

**Credit cost:** 0.25 credits per action

### Follow Profile

Follow a LinkedIn profile.

**Configuration**

| Field                    | Description                 |
| ------------------------ | --------------------------- |
| **LinkedIn Profile URL** | The profile to follow       |
| **Unfollow**             | Check to unfollow instead   |
| **LinkedIn Users**       | Users to perform the action |

**Credit cost:** 0.25 credits per action

### Visit Profile

Visit a LinkedIn profile (creates a profile view notification).

**Use cases**

* **Warm outreach** – View profiles before reaching out
* **Social presence** – Increase visibility with prospects

**Configuration**

| Field                    | Description                 |
| ------------------------ | --------------------------- |
| **LinkedIn Profile URL** | The profile to visit        |
| **LinkedIn Users**       | Users to perform the action |

**Credit cost:** 0.25 credits per action

### Like Post

React to a LinkedIn post.

**Configuration**

| Field                 | Description                                               |
| --------------------- | --------------------------------------------------------- |
| **LinkedIn Post URL** | The post to react to                                      |
| **Interaction type**  | Insightful, Love, Support, Celebrate, Like, Funny, Random |
| **LinkedIn Users**    | Users to perform the action                               |

**Credit cost:** 0.25 credits per action

### Comment Post

Leave a comment on a LinkedIn post.

**Configuration**

| Field                 | Description                 |
| --------------------- | --------------------------- |
| **LinkedIn Post URL** | The post to comment on      |
| **Comment**           | The comment text            |
| **LinkedIn Users**    | Users to perform the action |

**Credit cost:** 0.25 credits per action

***

## LinkedIn data models

Create data models from LinkedIn searches to trigger automated workflows.

### Available extractors

<AccordionGroup>
  <Accordion title="Fetch posts" icon="newspaper">
    Continuously fetch LinkedIn posts matching your search criteria.

    **Use cases**

    * Monitor brand mentions
    * Track competitor content
    * Identify engagement opportunities
  </Accordion>

  <Accordion title="Fetch people" icon="users">
    Fetch people from LinkedIn search results.

    **Use cases**

    * Build prospect lists from searches
    * Monitor specific searches for new matches
  </Accordion>

  <Accordion title="Fetch companies" icon="building">
    Fetch companies from LinkedIn search results.

    **Use cases**

    * Build target account lists
    * Monitor company searches for new matches
  </Accordion>

  <Accordion title="Fetch jobs" icon="briefcase">
    Fetch job postings from LinkedIn searches.

    **Use cases**

    * Monitor hiring signals
    * Track competitor job postings
  </Accordion>
</AccordionGroup>

### Audience extractors

These extractors read an audience you already own rather than a search, so
they run through one connected LinkedIn identity and do not rotate accounts.

<AccordionGroup>
  <Accordion title="Fetch page followers" icon="building-columns">
    Fetch the people who follow a LinkedIn company page, with the date each
    one followed. The connected identity must be an admin of the page.

    **Use cases**

    * Work inbound interest that never filled in a form
    * Track follower growth as named people instead of a count
  </Accordion>

  <Accordion title="Fetch followers" icon="user-plus">
    Fetch the people who follow the connected LinkedIn profile.

    **Use cases**

    * Turn a founder's audience into a prospect list
    * Spot buyers already following the team
  </Accordion>

  <Accordion title="Fetch company viewers" icon="eye">
    Fetch the people who viewed a LinkedIn company page over the past year.
    The connected identity must be an admin of the page, and the page must be
    on a Premium tier.

    **Use cases**

    * Catch accounts researching you before they reach out
    * Prioritize outbound by page-level intent
  </Accordion>
</AccordionGroup>


# LinkedIn Ads
Source: https://docs.getcargo.ai/integration/linkedin-ads

Fetch analytics data from your LinkedIn advertising campaigns

LinkedIn Ads is LinkedIn's advertising platform for reaching professionals. The Cargo integration enables you to sync campaign analytics data into your data models.

## Authentication

Connect to LinkedIn Ads using OAuth authentication.

<Info>
  You'll be prompted to authorize Cargo to access your LinkedIn Ads account.
</Info>

***

## Data models

### Fetch analytics

Retrieve analytics data from your LinkedIn Ads campaigns.

**Configuration**

| Field                | Description                         |
| -------------------- | ----------------------------------- |
| **Account ID**       | Your LinkedIn Ads account           |
| **Start Date**       | Start date for the analytics period |
| **Time Granularity** | Data aggregation level              |

**Time granularity options**

| Option  | Description        |
| ------- | ------------------ |
| All     | Aggregate all data |
| Daily   | Daily breakdown    |
| Monthly | Monthly breakdown  |
| Yearly  | Yearly breakdown   |

**Data returned**

Campaign performance metrics including impressions, clicks, spend, and engagement.

***

## Use cases

<AccordionGroup>
  <Accordion title="Campaign reporting" icon="chart-bar">
    Sync LinkedIn Ads performance data for unified reporting.
  </Accordion>

  <Accordion title="Attribution analysis" icon="chart-line">
    Combine ad data with CRM data for attribution modeling.
  </Accordion>

  <Accordion title="Budget optimization" icon="dollar-sign">
    Analyze spend efficiency across campaigns.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use daily granularity** - Daily data provides the best balance of detail and volume
2. **Set appropriate date ranges** - Avoid pulling excessive historical data
3. **Refresh regularly** - Data is fetched daily to keep metrics current


# LinkedIn Matched Audiences
Source: https://docs.getcargo.ai/integration/linkedin-matched-audience

Push companies and contacts into LinkedIn Matched Audiences for ad targeting

LinkedIn Matched Audiences (also called DMP segments) let you target ads to a custom list of companies or contacts on LinkedIn. The Cargo integration lets you create new audiences, push companies and contacts into them, and pull match-rate reports — all from your workflows.

## Authentication

Connect to LinkedIn Matched Audiences using OAuth.

<Info>
  Authentication is handled by [Polytomic](https://www.polytomic.com). When you click **Authenticate**, a Polytomic Connect modal opens where you sign in with your LinkedIn Ads account. Cargo only stores a Polytomic-managed reference to the connection — your LinkedIn credentials are never exposed to Cargo directly.
</Info>

The signed-in LinkedIn user must have access to the ad accounts you want to push audiences into.

***

## LinkedIn Matched Audience actions

### Create Audience

Create a new Matched Audience (DMP segment) on a LinkedIn Ads account.

**Configuration**

| Field             | Description                                                            |
| ----------------- | ---------------------------------------------------------------------- |
| **Ad account**    | LinkedIn ad account URN (e.g. `urn:li:sponsoredAccount:516848833`)     |
| **Audience name** | Display name for the new DMP segment                                   |
| **Type**          | `Users (contacts)` or `Companies` — determines what can be added to it |

**Returns**

The newly created `audienceId`, plus the `name`, `account`, and `type` you used to create it.

<Tip>
  Pick the audience **Type** carefully — a `USER` audience can only accept contacts and a `COMPANY` audience can only accept companies. You cannot change the type after creation.
</Tip>

### Add Company to Audience

Add a single company to an existing company-type Matched Audience.

**Configuration**

| Field                                       | Description                                        |
| ------------------------------------------- | -------------------------------------------------- |
| **Ad account**                              | LinkedIn ad account URN (used to filter audiences) |
| **Audience**                                | DMP segment to add the company to                  |
| **Company name**                            | Required                                           |
| **Company website domain**                  | Optional, e.g. `cargo.ai`                          |
| **LinkedIn company page URL**               | Optional                                           |
| **Stock symbol**                            | Optional                                           |
| **Industries**                              | Optional, one or many                              |
| **City**, **State**, **Country (ISO code)** | Optional location attributes                       |

<Tip>
  Provide as many identifiers as you have (domain, LinkedIn page URL, stock symbol). LinkedIn uses them to improve match rates.
</Tip>

### Add Contact to Audience

Add a single contact to an existing user-type Matched Audience.

**Configuration**

| Field                                                                   | Description                                                               |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **Ad account**                                                          | LinkedIn ad account URN (used to filter audiences)                        |
| **Audience**                                                            | DMP segment to add the contact to                                         |
| **Email**                                                               | Lowercased and SHA-256 hashed automatically before being sent to LinkedIn |
| **Google Advertising ID**                                               | Optional GAID identifier                                                  |
| **First name**, **Last name**, **Title**, **Company name**, **Country** | Optional contact attributes that improve matching                         |

<Warning>
  At least one of **Email** or **Google Advertising ID** is required.
</Warning>

<Info>
  Cargo lowercases and SHA-256 hashes emails before sending them to LinkedIn, as required by the LinkedIn Marketing API. You only need to provide the raw email — the hashing happens automatically.
</Info>

### Remove Email from Audience

Remove a contact from a user-type Matched Audience by their email address.

**Configuration**

| Field          | Description                                                               |
| -------------- | ------------------------------------------------------------------------- |
| **Ad account** | LinkedIn ad account URN (used to filter audiences)                        |
| **Audience**   | DMP segment to remove the contact from                                    |
| **Email**      | Lowercased and SHA-256 hashed automatically before being sent to LinkedIn |

### Create Report

Fetch the match-rate / sample-size report for a Matched Audience.

**Configuration**

| Field          | Description                                        |
| -------------- | -------------------------------------------------- |
| **Ad account** | LinkedIn ad account URN (used to filter audiences) |
| **Audience**   | DMP segment to fetch the report for                |

**Returns**

| Field            | Description                                    |
| ---------------- | ---------------------------------------------- |
| `audienceId`     | The DMP segment ID                             |
| `sampleSize`     | LinkedIn's estimated number of matched members |
| `sampleType`     | The kind of sample LinkedIn returned           |
| `audienceCounts` | Counts broken down by audience source          |

<Info>
  LinkedIn populates match data asynchronously after you push records into an audience. New audiences typically take 24–48 hours before reports show meaningful match rates.
</Info>

***

## Use cases

<AccordionGroup>
  <Accordion title="ABM ad targeting" icon="bullseye">
    Push your target accounts from your CRM or warehouse into a company audience and run LinkedIn ABM campaigns against them.
  </Accordion>

  <Accordion title="Contact retargeting" icon="users">
    Sync engaged contacts (e.g. event attendees, trial signups, MQLs) into a user audience and retarget them on LinkedIn.
  </Accordion>

  <Accordion title="Suppression lists" icon="user-slash">
    Keep a Matched Audience of customers or unsubscribed contacts in sync, then exclude it from campaigns to avoid wasting spend.
  </Accordion>

  <Accordion title="Match-rate monitoring" icon="chart-line">
    Use **Create Report** in a scheduled workflow to track audience match rates over time and alert when they drop.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Match the audience type to your data** — Use `USER` audiences for contacts (email/GAID) and `COMPANY` audiences for accounts. They are not interchangeable.
2. **Push as many identifiers as possible** — For companies, provide domain, LinkedIn page URL, and stock symbol when available; for contacts, include name, title, company, and country alongside email. More identifiers means a higher match rate.
3. **Hash on Cargo, not in your warehouse** — Send raw emails to the action; Cargo handles the lowercase + SHA-256 step LinkedIn requires.
4. **Keep audiences in sync incrementally** — Add new records as they qualify and use **Remove Email from Audience** for unsubscribes or churned customers, instead of recreating audiences from scratch.
5. **Wait before reading match rates** — Schedule **Create Report** at least 24 hours after pushing new records. LinkedIn needs time to compute the match.


# Linkup
Source: https://docs.getcargo.ai/integration/linkup

Search the web and get AI-powered answers with Linkup

Linkup is an AI-powered search API that provides real-time web search results and structured answers. The Cargo integration enables you to enrich your data with live web information.

## Authentication

Connect to Linkup using your API key.

### Connection details

| Field       | Description         |
| ----------- | ------------------- |
| **API key** | Your Linkup API key |

***

## Linkup actions

### Search

Search the web for relevant content using natural language queries.

**Configuration**

| Field            | Description                                  |
| ---------------- | -------------------------------------------- |
| **Query**        | Natural language question or search query    |
| **Search Depth** | Standard (quick) or Deep (thorough, agentic) |

**Search depth options**

| Depth        | Description                           | Credits |
| ------------ | ------------------------------------- | ------- |
| **Standard** | Quick search with standard accuracy   | 0.5     |
| **Deep**     | Thorough search with agentic thinking | 2       |

### Instruct

Get structured or sourced answers to your questions.

**Configuration**

| Field                        | Description                                        |
| ---------------------------- | -------------------------------------------------- |
| **Query**                    | Natural language question                          |
| **Search Depth**             | Standard or Deep search                            |
| **Output Type**              | Sourced answer or Structured response              |
| **Structured Output Schema** | JSON schema for structured responses (if selected) |

**Output types**

| Type               | Description                     |
| ------------------ | ------------------------------- |
| **Sourced answer** | Direct answer with source links |
| **Structured**     | Custom-formatted JSON response  |

<Tip>
  Use structured output to extract specific data points like company information, product details, or competitive intelligence.
</Tip>

***

## Credits

| Action   | Cost                       |
| -------- | -------------------------- |
| Search   | 0.5 (standard) or 2 (deep) |
| Instruct | 1 credit per request       |

***

## Use cases

<AccordionGroup>
  <Accordion title="Company research" icon="building">
    Get real-time information about companies, products, and news.
  </Accordion>

  <Accordion title="Competitive intelligence" icon="magnifying-glass">
    Research competitors and market trends with sourced answers.
  </Accordion>

  <Accordion title="Data enrichment" icon="database">
    Enrich records with live web data using structured outputs.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use deep search for complex queries** - Deep search provides more thorough results for nuanced questions
2. **Define clear schemas** - For structured output, define precise JSON schemas for consistent results
3. **Include context in queries** - More specific queries yield better results


# Livestorm
Source: https://docs.getcargo.ai/integration/livestorm

Connect Livestorm to pull webinar attendees and event data into your workflows.

## How to set up Livestorm

### Authentication

Livestorm uses API key authentication:

1. Log in to your Livestorm account
2. Navigate to **Settings** → **Integrations** → **API**
3. Generate or copy your API key
4. Paste the API key in Cargo when connecting

## Livestorm data models

### Fetch people

Pull all people (registrants and attendees) from your Livestorm account.

**Features:**

* Incremental sync (only new/updated people)
* Minimum 30-minute sync interval
* Unifies contacts by email

**Data includes:**

* Email address
* First name, last name
* Registration status
* Attendance data
* Custom field responses

**Use cases:**

* Sync webinar registrants to your CRM
* Trigger follow-up workflows based on registration
* Build segments of webinar attendees

### Fetch events

Pull all events (webinars) from your Livestorm account.

**Features:**

* Incremental sync
* Minimum 30-minute sync interval

**Data includes:**

* Event name and slug
* Event status
* Scheduled date/time
* Event settings

**Use case:** Track webinar performance and sync event metadata.

### Fetch sessions

Pull all sessions (individual webinar occurrences) from Livestorm.

**Features:**

* Incremental sync
* Minimum 30-minute sync interval

**Data includes:**

* Session date/time
* Session status
* Attendee count
* Duration

**Use case:** Track session-level attendance and engagement.

## Response data

### People data includes:

| Field              | Description              |
| ------------------ | ------------------------ |
| email              | Contact email address    |
| first\_name        | First name               |
| last\_name         | Last name                |
| registrant\_detail | Registration information |
| attendance         | Attendance status        |
| custom\_fields     | Form field responses     |
| created\_at        | Registration timestamp   |

### Events data includes:

| Field               | Description     |
| ------------------- | --------------- |
| title               | Webinar title   |
| slug                | URL slug        |
| status              | Event status    |
| estimated\_duration | Expected length |
| timezone            | Event timezone  |

## Best practices

* Use incremental sync to capture new registrants quickly
* Segment attendees vs. no-shows for different follow-up
* Capture custom field data for lead qualification
* Sync before webinar for sales prep, after for follow-up
* Combine with enrichment to complete attendee profiles


# Lusha
Source: https://docs.getcargo.ai/integration/lusha

Connect Lusha to enrich contacts and companies with verified contact information.

## How to set up Lusha

### Authentication

Lusha uses API key authentication:

1. Log in to your Lusha account
2. Navigate to **Settings** → **API**
3. Generate or copy your API key
4. Paste the API key in Cargo when connecting

## Lusha actions

### Enrich

Retrieve detailed information about a person or company.

**For Person enrichment:**

**Required fields:**

* **Object type**: Person
* **Fields**: Provide identifying information:
  * First name
  * Last name
  * Email
  * Company name
  * Company domain
  * LinkedIn URL
* **Filter by**: Choose to return Email or Phone data

**Optional fields:**

* **Refresh Job Info**: Enable real-time job updates

> **Tip:** Provide at least first name, last name, and company name or domain for best results.

**For Company enrichment:**

**Required fields:**

* **Object type**: Company
* **Fields**: Provide company name or domain

**Use cases:**

* Enrich leads with verified email addresses
* Find direct phone numbers for sales outreach
* Verify and update contact information
* Get company firmographic data

### Search

Search for contacts or companies matching specific criteria.

**For Contact search:**

* **Fields**: Define contact search criteria
* **Company fields**: Filter by company attributes
* **Limit**: Maximum records to return

**For Company search:**

* **Fields**: Define company search criteria
* **Limit**: Maximum records to return

**Use cases:**

* Build targeted prospect lists
* Find contacts at specific companies
* Discover companies matching your ICP

## Credits

Lusha uses a credit-based system:

* **Search**: 3 credits per search (fixed) or 3 credits per item when enriching
* **Enrich**: 3 credits per request

Cargo tracks credit usage and supports caching to optimize costs.

## Enrichment data

### Person data includes:

* Full name
* Email addresses (work and personal)
* Phone numbers (direct, mobile)
* Current job title
* Company information
* LinkedIn profile
* Location

### Company data includes:

* Company name
* Domain
* Industry
* Employee count
* Location
* Revenue range
* LinkedIn company page

## Best practices

* Provide multiple data points for higher match rates
* Use caching to avoid re-enriching the same contacts
* Enable "Refresh Job Info" for contacts that may have changed roles
* Combine with other enrichment sources for comprehensive profiles

## Rate limits

Lusha API allows up to 50 requests per second. Cargo handles rate limiting automatically.


# Manus
Source: https://docs.getcargo.ai/integration/manus

Run AI agent tasks with Manus

Manus is an AI agent platform that can execute complex tasks autonomously. The Cargo integration enables you to create and run Manus tasks within your workflows.

## Authentication

Connect to Manus using your API key.

### Connection details

| Field       | Description        |
| ----------- | ------------------ |
| **API Key** | Your Manus API key |

***

## Manus actions

### Create task

Create and execute an AI agent task.

**Configuration**

| Field             | Description                   |
| ----------------- | ----------------------------- |
| **Prompt**        | Instructions for the AI agent |
| **Agent profile** | AI model to use               |
| **Task mode**     | Execution mode                |
| **Attachments**   | Files or URLs to include      |

**Agent profiles**

| Profile        | Description           |
| -------------- | --------------------- |
| Manus 1.5      | Full capability agent |
| Manus 1.5 Lite | Lighter, faster agent |

**Task modes**

| Mode     | Description                     |
| -------- | ------------------------------- |
| Chat     | Conversational interaction      |
| Adaptive | Adapts approach based on task   |
| Agent    | Full autonomous agent execution |

**Attachments**

You can attach files to provide context:

* **URL**: Reference a file by URL
* **File**: Include file data directly

***

## Use cases

<AccordionGroup>
  <Accordion title="Research automation" icon="magnifying-glass">
    Automate research tasks like competitive analysis.
  </Accordion>

  <Accordion title="Content generation" icon="file-lines">
    Generate personalized content at scale.
  </Accordion>

  <Accordion title="Data extraction" icon="database">
    Extract structured data from unstructured sources.
  </Accordion>

  <Accordion title="Complex workflows" icon="diagram-project">
    Execute multi-step tasks that require reasoning.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Be specific in prompts** - Clear instructions lead to better results
2. **Choose the right mode** - Use Agent mode for complex autonomous tasks
3. **Include context** - Attach relevant files to provide necessary context


# Marketo
Source: https://docs.getcargo.ai/integration/marketo

Connect Marketo to manage custom objects in your workflows.

## How to set up Marketo

### Authentication

Marketo uses a LaunchPoint custom service for API access:

1. In Marketo, go to Admin → LaunchPoint and create (or open) a custom service
2. Copy the service's Client ID and Client Secret
3. Find your Munchkin ID under Admin → Munchkin (e.g. `123-ABC-456`)
4. In Cargo, paste the Munchkin ID, Client ID, and Client Secret when connecting

<Note>
  **Code slugs** — integration slug: `marketo`. Actions: `createObject`, `updateObjects`, `upsertObjects`, `deleteObjects`, `getObject`, `findObjects`. Call them as `integrations.marketo.<action>(...)`.
</Note>

Cargo spreads requests at up to 5 calls per second to stay within Marketo's API limits (100 calls per 20 seconds) while leaving headroom for concurrency.

All actions operate on Marketo custom objects, selected by their API name.

## Marketo actions

### Create object

Insert a new object (`action: createOnly`, `dedupeBy: dedupeFields`). Marketo skips objects whose dedupe key already exists; check the response data for `status: skipped` to detect duplicates.

**Required fields:**

* **Object type**: API name of the Marketo object type
* **Fields**: Fields to write on the new object. Must include every dedupe field configured on the object — Marketo rejects creates that don't supply the full dedupe key

**Use case:** Push new records from your workflows into Marketo custom objects.

### Update objects

Look up objects by a searchable field, then update every match by `marketoGUID`.

**Required fields:**

* **Object type**: API name of the Marketo object type
* **Matching field**: Field used to look up the objects to update. Must be one of the object's searchable fields (`marketoGUID`, dedupe fields, or any other indexed field)
* **Matching value**: Value to match against the matching field. All matched objects are updated
* **Fields to update**: Fields to write on every matched object

**Use case:** Keep Marketo custom object records in sync when data changes upstream.

### Upsert objects

Look up objects by a dedupe field; update every match by `marketoGUID`, or create a new object if none match.

**Required fields:**

* **Object type**: API name of the Marketo object type
* **Matching field**: Field used to look up the objects. Must be one of the object's dedupe fields so the object can be created if no match is found. For objects with compound dedupe keys, include the other dedupe field(s) in the mappings
* **Matching value**: Value to match. All matched objects are updated; if no match is found, a new object is created with this value on the matching field
* **Fields to write**: Fields to write on the matched records (or the new record)

**Use case:** Sync records into Marketo without worrying whether they already exist.

### Delete objects

Look up objects by a searchable field, then delete every match by `marketoGUID`.

**Required fields:**

* **Object type**: API name of the Marketo object type
* **Matching field**: Field used to look up the objects to delete. Must be one of the object's searchable fields
* **Matching value**: Value to match. All matched objects are deleted

**Use case:** Clean up stale or invalid custom object records from workflows.

### Get object

Get a single object by `marketoGUID`.

**Required fields:**

* **Object type**: API name of the Marketo object type
* **Marketo GUID**: The `marketoGUID` of the object to retrieve

**Use case:** Fetch the full record for an object you already have a GUID for.

### Find objects

Look up objects by any searchable-field value. Returns every match.

**Required fields:**

* **Object type**: API name of the Marketo object type
* **Filter field**: Field to filter on. Must be one of the object's searchable fields
* **Filter values**: Values to look up. Larger inputs are automatically chunked

**Use case:** Retrieve matching Marketo records to enrich or branch on in a workflow.

## Best practices

* Include every dedupe field when creating objects — Marketo rejects partial dedupe keys
* Prefer **Upsert objects** when you can't guarantee whether a record exists
* Use dedupe fields or indexed fields for lookups; non-searchable fields will fail
* Watch for `status: skipped` in create responses to detect duplicates


# Metabase
Source: https://docs.getcargo.ai/integration/metabase

Connect Metabase to run saved questions and SQL, sync question results into models, and give agents access to your Metabase.

## How to set up Metabase

### Authentication

Metabase authenticates with an API key:

1. In Metabase, go to **Admin** → **Settings** → **Authentication** → **API keys**
2. Create a key and assign it to a group. The key inherits that group's permissions, so give it a group that can see the databases and collections you want to reach from Cargo
3. Copy the key — Metabase only shows it once
4. In Cargo, enter:
   * **Instance URL**: the address of your Metabase, for example `https://mycompany.metabaseapp.com`
   * **API Key**: the key you just created

Cargo verifies the connection by listing the databases the key can see.

## Metabase actions

### Run question

Runs a saved question and returns its rows.

**Configuration:**

* **Question**: the saved question to run
* **Parameters** (optional): Metabase parameter objects, each with a `type`, a `target` and a `value`

Values are returned unformatted, so numbers stay numbers and dates stay dates rather than arriving as the strings shown in the Metabase interface.

### Run SQL

Runs a SQL query against a database connected to Metabase.

**Configuration:**

* **Database**: the target database
* **SQL**: the query to run

The API key's group needs native query permission on that database. Metabase caps this endpoint at 2000 rows; when a result hits the cap the action reports that it was truncated.

### Search entities

Searches questions, models, metrics, dashboards, collections and tables.

**Configuration:**

* **Query**: the search term
* **Entity types** (optional): restrict the search
* **Limit** (optional): defaults to 25, up to 100

## Metabase data models

### Fetch question

Syncs the rows of a saved question into a Cargo model.

**Configuration:**

* **Question**: the saved question to sync
* **ID column**: the column that uniquely identifies a row
* **Title column**: the column used as the record title

**Features:**

* **Full refresh**: each run replaces the model with a fresh snapshot, since Metabase exposes no cursor over a question's results
* **Minimum interval**: 1 hour between syncs

Metabase results have no identifier of their own, which is why you pick the ID column yourself. Choose one that is unique and stable across runs — a primary key from the underlying table, or the grouping column of an aggregate. If a run comes back with rows but no ID values, the sync fails on purpose rather than overwriting what was synced last time.

A question that returns 50,000 rows or more is rejected: add a filter or an aggregation to narrow it down.

Column names come from the question's columns and must contain only letters, numbers, underscores and spaces. Rename them in Metabase if a sync reports invalid columns.

## MCP server

Metabase hosts its own MCP server, so a Metabase connector can be attached directly to a Cargo agent. The agent gets Metabase's own tools: searching tables and metrics, reading entities, constructing and executing queries, running SQL, and creating questions and dashboards.

Before this works, a Metabase admin must turn the MCP server on under **Admin** → **AI** → **MCP**, and AI features must be enabled for the instance. If the connector authenticates but the agent cannot reach any tools, that setting is the first thing to check.

## Best practices

* Give the API key its own group with the narrowest permissions that cover your use case, rather than reusing an admin group
* Prefer saved questions over ad-hoc SQL for anything recurring: the question stays reviewable in Metabase and its columns are typed
* Aggregate in Metabase before syncing. Full refresh means every run pays for the whole result set, so a question returning a rolled-up few thousand rows beats one returning raw events
* Use the MCP server for exploratory questions from agents, and actions for the deterministic steps of a workflow


# Microsoft Teams
Source: https://docs.getcargo.ai/integration/microsoft-teams

Connect Microsoft Teams to send messages to channels and chats from your workflows.

## How to set up Microsoft Teams

### Authentication

Microsoft Teams uses OAuth 2.0 authentication:

1. Click the Connect button in Cargo
2. Sign in with your Microsoft account
3. Grant consent for Cargo to send messages
4. Connection is established automatically

**Required permissions:**

* Send messages to channels
* Send messages to chats
* Read team and channel information

## Microsoft Teams actions

### Create channel message

Send a message to a Teams channel.

**Required fields:**

* **Team**: Select the team containing the channel
* **Channel**: Select the target channel
* **Content Type**: Choose Plain Text or HTML
* **Message**: The message content (supports expressions)

**Use cases:**

* Send lead notifications to sales channels
* Alert teams about important events
* Share workflow status updates
* Notify about deal stage changes

### Create chat message

Send a message to a Teams chat (direct message or group chat).

**Required fields:**

* **Chat**: Select the chat to message
* **Content Type**: Choose Plain Text or HTML
* **Message**: The message content (supports expressions)

**Use cases:**

* Send direct notifications to specific users
* Alert managers about high-priority leads
* Notify individuals about assigned tasks

## Message formatting

### Plain Text

Simple text messages without formatting.

```
New lead from {{company_name}}
Contact: {{first_name}} {{last_name}}
Email: {{email}}
```

### HTML

Rich formatted messages with styling.

```html theme={null}
<b>New Lead Alert</b><br>
Company: {{company_name}}<br>
Contact: {{first_name}} {{last_name}}<br>
<a href="mailto:{{email}}">{{email}}</a>
```

**Supported HTML elements:**

* `<b>`, `<strong>` - Bold text
* `<i>`, `<em>` - Italic text
* `<a href="">` - Links
* `<br>` - Line breaks
* `<ul>`, `<ol>`, `<li>` - Lists

## Example messages

### Lead notification

```
🆕 New Lead

Company: {{company_name}}
Contact: {{first_name}} {{last_name}}
Title: {{job_title}}
Source: {{lead_source}}

View in CRM: {{crm_link}}
```

### Deal won celebration

```
🎉 Deal Won!

{{company_name}} - ${{deal_value}}
Owner: {{sales_rep}}
Close Date: {{close_date}}

Great work, team!
```

### Task assignment

```
📋 Task Assigned

Lead: {{first_name}} {{last_name}} at {{company_name}}
Action: {{task_description}}
Due: {{due_date}}

Please follow up within 24 hours.
```

## Rate limits

Microsoft Teams API has a rate limit of 50 requests per second. Cargo handles rate limiting automatically to ensure reliable message delivery.

## Best practices

* Use descriptive emojis to make messages scannable
* Include relevant links for quick access
* Keep messages concise and actionable
* Use HTML formatting for complex information
* Set up dedicated channels for different alert types
* Consider message frequency to avoid notification fatigue


# Mixpanel
Source: https://docs.getcargo.ai/integration/mixpanel

Connect Mixpanel to pull product analytics events into your workflows.

## How to set up Mixpanel

### Authentication

Mixpanel requires service account credentials:

1. Log in to your Mixpanel account

2. Navigate to **Settings** → **Project Settings** → **Service Accounts**

3. Create a new service account or use an existing one

4. Gather the following credentials:
   * **Username**: Service account username
   * **Secret Key**: Service account secret
   * **Project ID**: Your Mixpanel project ID (found in Project Settings)

5. Enter these credentials in Cargo when connecting

## Mixpanel data models

### Fetch events

Pull product analytics events from Mixpanel into Cargo.

**Configuration:**

* **From date**: Start date for fetching events

**Features:**

* **Incremental sync**: Only fetches new events since the last sync
* **Minimum interval**: 12 hours between syncs

**Use cases:**

* Trigger workflows based on product usage patterns
* Identify highly engaged users for sales outreach
* Build lead scoring models using product analytics
* Create segments based on feature adoption

## Event data

Mixpanel events typically include:

| Field        | Description             |
| ------------ | ----------------------- |
| event        | Event name              |
| distinct\_id | User identifier         |
| time         | Event timestamp         |
| properties   | Custom event properties |

## Best practices

* Use consistent `distinct_id` values that map to your CRM contacts
* Define key activation and engagement events in Mixpanel
* Set appropriate sync intervals based on your workflow needs
* Combine Mixpanel data with enrichment data for complete lead profiles


# Mixrank
Source: https://docs.getcargo.ai/integration/mixrank

Find people and companies with Mixrank B2B data

Mixrank is a B2B data platform that provides company and contact information for sales and marketing teams. The Cargo integration enables you to find and enrich person and company records.

## Authentication

Connect to Mixrank using your API key.

### Connection details

| Field       | Description          |
| ----------- | -------------------- |
| **API key** | Your Mixrank API key |

***

## Mixrank actions

### Find person

Find a person using various identifiers.

**Configuration**

| Field            | Description                         |
| ---------------- | ----------------------------------- |
| **Email**        | Email address of the person         |
| **Domain**       | Company domain (e.g., apple.com)    |
| **Name**         | Full name of the person             |
| **First name**   | First name of the person            |
| **Last name**    | Last name of the person             |
| **Phone**        | Phone number of the person          |
| **Social URL**   | Social media profile URL (LinkedIn) |
| **Company name** | Company where the person works      |

### Find company

Retrieve company information.

**Configuration**

| Field            | Description                |
| ---------------- | -------------------------- |
| **Name**         | Company name (e.g., Xerox) |
| **URL**          | Domain or website URL      |
| **LinkedIn URL** | Company's LinkedIn URL     |

***

## Credits

| Action       | Cost      |
| ------------ | --------- |
| Find person  | 4 credits |
| Find company | 4 credits |

***

## Use cases

<AccordionGroup>
  <Accordion title="Lead enrichment" icon="user-plus">
    Enrich leads with contact details using email or social profiles.
  </Accordion>

  <Accordion title="Company research" icon="building">
    Get detailed company information from domain or LinkedIn.
  </Accordion>

  <Accordion title="Data hygiene" icon="broom">
    Validate and complete contact records with verified data.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use multiple identifiers** - Provide email + domain for better match rates
2. **Leverage LinkedIn** - Social URLs often provide the best matching results
3. **Cache results** - Results are cached to reduce credit usage on repeated lookups


# NetSuite
Source: https://docs.getcargo.ai/integration/netsuite

Connect your NetSuite ERP to sync and manage business records

NetSuite is a cloud-based enterprise resource planning (ERP) software that helps businesses manage financials, operations, and customer relationships. The Cargo integration enables you to sync and manage records across all your NetSuite objects.

## Authentication

NetSuite uses Token-Based Authentication (TBA) for secure API access.

### Connection details

| Field               | Description              |
| ------------------- | ------------------------ |
| **Account ID**      | Your NetSuite account ID |
| **Consumer Key**    | OAuth consumer key       |
| **Consumer Secret** | OAuth consumer secret    |
| **Token**           | Access token             |
| **Token Secret**    | Access token secret      |

<Tip>
  Generate your credentials in NetSuite under **Setup → Integration → Manage Integrations**.
</Tip>

<Note>
  A companion **Netsuite (SOAP)** integration (catalog slug `netsuiteSoap`)
  talks to NetSuite's SuiteTalk SOAP web services instead of the API used
  here. It authenticates with the same token-based credentials and exposes a
  single **Insert record** action (returning the created record's id). Use it
  when a record type is only writable through the SOAP interface; use this
  integration for everything else.
</Note>

***

## NetSuite actions

<Tip>
  NetSuite actions support all standard and custom record types in your account.
</Tip>

### Search records

Retrieve multiple records from any NetSuite object.

**Configuration**

| Field           | Description                                |
| --------------- | ------------------------------------------ |
| **Object type** | Select the record type to search           |
| **Filter**      | Define filter conditions                   |
| **Sort**        | Sort results by field                      |
| **Limit**       | Maximum records to retrieve (default: 100) |

### Insert record

Create a new record in NetSuite.

**Configuration**

| Field           | Description                     |
| --------------- | ------------------------------- |
| **Object type** | Select the record type          |
| **Mappings**    | Map field values for the record |

### Update records

Update existing records in NetSuite.

**Configuration**

| Field                               | Description                             |
| ----------------------------------- | --------------------------------------- |
| **Object type**                     | Select the record type                  |
| **Matching Value**                  | Value to match against                  |
| **Netsuite Matching Property Name** | Property to match on                    |
| **Mappings**                        | Map fields to update                    |
| **Skip if exist**                   | Update only if field is currently empty |

### Upsert records

Insert or update records based on a matching field.

**Configuration**

| Field                               | Description                             |
| ----------------------------------- | --------------------------------------- |
| **Object type**                     | Select the record type                  |
| **Matching Value**                  | Value to match against                  |
| **Netsuite Matching Property Name** | Property to match on                    |
| **Mappings**                        | Map field values                        |
| **Skip if exist**                   | Update only if field is currently empty |

### Delete records

Delete records from NetSuite.

**Configuration**

| Field                               | Description            |
| ----------------------------------- | ---------------------- |
| **Object type**                     | Select the record type |
| **Matching Value**                  | Value to match against |
| **Netsuite Matching Property Name** | Property to match on   |

<Warning>
  Delete operations are permanent. Ensure you have proper filters configured.
</Warning>

***

## Data models

Create data models from any NetSuite record type with incremental sync support.

### Configuration

| Field           | Description                    |
| --------------- | ------------------------------ |
| **Object type** | Select the record type to sync |

### Supported record types

<AccordionGroup>
  <Accordion title="Financial records" icon="dollar-sign">
    Sync invoices, transactions, journal entries, and other financial data.
  </Accordion>

  <Accordion title="Customer records" icon="users">
    Sync customer and contact information with full relationship data.
  </Accordion>

  <Accordion title="Inventory records" icon="boxes-stacked">
    Track inventory items, locations, and stock levels.
  </Accordion>

  <Accordion title="Custom records" icon="puzzle-piece">
    Access any custom record types defined in your NetSuite instance.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use incremental sync** - NetSuite data models support incremental sync for efficient updates
2. **Rate limits** - NetSuite has strict rate limits (15 requests/minute). Plan workflows accordingly
3. **Custom fields** - All custom fields are automatically available through dynamic field selection


# NeverBounce
Source: https://docs.getcargo.ai/integration/never-bounce

Connect NeverBounce to verify email addresses and maintain list hygiene in your workflows.

## How to set up NeverBounce

### Authentication

NeverBounce uses API key authentication:

1. Sign up at [neverbounce.com](https://neverbounce.com)
2. Navigate to **API** in your dashboard
3. Copy your API key
4. Paste the API key in Cargo when connecting

## NeverBounce actions

### Verify email

Check if an email address is valid and deliverable.

**Required fields:**

* **Email**: The email address to verify

**Credits:** 0.2 credits per verification

## Verification results

NeverBounce returns clear verification statuses:

| Result     | Description                       | Action           |
| ---------- | --------------------------------- | ---------------- |
| valid      | Email exists and is deliverable   | Safe to email    |
| invalid    | Email does not exist or bounces   | Remove from list |
| disposable | Temporary/throwaway email address | Avoid emailing   |
| catchall   | Domain accepts all emails         | Use caution      |
| unknown    | Unable to determine status        | Retry later      |

## Response data

| Field                 | Description                         |
| --------------------- | ----------------------------------- |
| result                | Verification result                 |
| flags                 | Additional flags (role, free, etc.) |
| suggested\_correction | Typo correction suggestion          |
| execution\_time       | Time taken to verify                |

## Best practices

* Verify emails at point of capture for best data quality
* Re-verify periodically (recommended every 3-6 months)
* Treat "catchall" emails as valid but monitor for bounces
* Remove "disposable" emails - they indicate low-quality leads
* Use suggested corrections to fix typos automatically
* Cache results to avoid redundant verification

## Integration benefits

* **Improved deliverability**: Only email verified addresses
* **Better sender reputation**: Reduce bounce rates
* **Cost savings**: Don't pay to email invalid addresses
* **Higher engagement**: Focus on real contacts


# Notion MCP
Source: https://docs.getcargo.ai/integration/notion-mcp

Connect Notion's hosted MCP server so your AI agents can search and update your Notion workspace.

Notion MCP connects Notion's hosted MCP (Model Context Protocol) server to Cargo so [AI agents](/agents/tools-and-actions#mcp-servers) can search and update your Notion workspace. Authorization is browser-based OAuth — no Notion integration token or API key is required.

## How to set up Notion MCP

### Authentication

Notion MCP uses OAuth authorization:

1. Create a Notion MCP connector in Cargo
2. Click **Authorize Notion MCP**
3. Sign in to Notion in the popup and choose which workspace to grant access to
4. Cargo stores the resulting token and refreshes it automatically

<Note>
  **Code slugs** — integration slug: `notionMcp`. This integration exposes no fixed actions: its tools are discovered from Notion's MCP server at runtime and made available to agents.
</Note>

## Notion MCP tools

The connector does not define static actions. When attached to an agent as an MCP server, the agent lists the tools Notion's server advertises at runtime — searching pages, reading and updating content — and can call any of them. See [MCP servers](/agents/tools-and-actions#mcp-servers) for how agents use MCP tools.

Related MCP integrations: [HubSpot MCP](/integration/hubspot-mcp) and [Salesforce MCP](/integration/salesforce-mcp).

## Best practices

* Grant access only to the Notion workspace (and pages) your agents actually need
* Authorize with a Notion user whose permissions match what you want agents to be able to do
* Re-authorize the connector if access is revoked from Notion's connected-apps settings


# Ocean.io
Source: https://docs.getcargo.ai/integration/oceanio

Connect Ocean.io for lookalike company discovery and contact enrichment in your workflows.

## How to set up Ocean.io

### Authentication

Ocean.io uses API key authentication:

1. Sign up at [ocean.io](https://ocean.io)
2. Navigate to your API settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## Ocean.io actions

### Enrich company

Get detailed company information from various identifiers.

**Company fields:**

* **Name**: Company name
* **Domain**: Company domain
* **Registration number**: Company registration ID
* **Email / Phone**: Contact information
* **Address details**: Country, state, city, street, postal code
* **Social profiles**: LinkedIn, Facebook, Twitter, Instagram, YouTube, Xing

**People (optional):** Include associated contacts with their details.

**Credits:** 1 credit per request

### Enrich person

Get detailed person information with company context.

**Person fields:**

* **ID / Name**: Person identifier
* **First name / Last name**: Full name
* **Job title**: Role at company
* **Email / Phone**: Contact information
* **Social profiles**: LinkedIn, Facebook, Twitter
* **Country**: Location

**Company fields:** Same as company enrichment for context.

**Credits:** 1 credit per request

### Search companies

Find companies matching specific criteria.

**Company filters:**

| Filter                  | Description                |
| ----------------------- | -------------------------- |
| Lookalike domains       | Find similar companies     |
| Include/Exclude domains | Domain lists               |
| LinkedIn industries     | Industry classification    |
| Company sizes           | Employee count ranges      |
| Revenues                | Revenue ranges             |
| Countries / States      | Geographic filters         |
| Technologies            | Tech stack filters         |
| Keywords                | Keyword matching           |
| Year founded            | Founding date range        |
| Web traffic             | Traffic volume filters     |
| E-commerce              | E-commerce businesses only |

**People filters:**

| Filter         | Description                       |
| -------------- | --------------------------------- |
| Job titles     | Role filters                      |
| Seniorities    | Level filters (C-Level, VP, etc.) |
| Departments    | Department filters                |
| Email statuses | Email validity filters            |
| Countries      | Person location                   |

**Credits:** 1 credit per result

### Search people

Find people matching specific criteria.

**People filters:** Same as search companies people filters.

**Company filters:** Same as search companies company filters.

**Credits:** 1 credit per result (fixed)

## Credits

All Ocean.io actions use a credit-based system:

| Action           | Credits      |
| ---------------- | ------------ |
| Enrich company   | 1 (fixed)    |
| Enrich person    | 1 (fixed)    |
| Search companies | 1 per result |
| Search people    | 1 (fixed)    |

## Rate limits

Ocean.io API has a rate limit of 60 requests per minute. Cargo handles rate limiting automatically.

## Best practices

* Use lookalike search to find similar companies to your best customers
* Combine company and people filters for precise targeting
* Filter by technologies for competitive displacement campaigns
* Include people in company enrichment for one-call contact discovery
* Use email status filters to ensure deliverability


# Octave
Source: https://docs.getcargo.ai/integration/octave

Run AI-powered sales agents with Octave

Octave is an AI platform for sales automation that provides agents for email generation, lead qualification, prospecting, and enrichment. The Cargo integration enables you to run Octave agents within your workflows.

## Authentication

Connect to Octave using your API key.

### Connection details

| Field       | Description         |
| ----------- | ------------------- |
| **API key** | Your Octave API key |

***

## Octave actions

### Run sequence

Generate personalized email sequences for prospects.

**Configuration**

| Field                            | Description             |
| -------------------------------- | ----------------------- |
| **Agent**                        | Select an EMAIL agent   |
| **Email**                        | Prospect's email        |
| **Job title**                    | Prospect's job title    |
| **Company domain**               | Company domain          |
| **Company name**                 | Company name            |
| **First name**                   | Prospect's first name   |
| **LinkedIn profile**             | LinkedIn profile URL    |
| **Language**                     | Output language         |
| **Output format**                | Text, HTML, or Markdown |
| **Runtime context/instructions** | Per-step customization  |

### Qualify person

Score and qualify individual prospects.

**Configuration**

| Field               | Description                    |
| ------------------- | ------------------------------ |
| **Agent**           | Select a QUALIFY\_PERSON agent |
| **Email**           | Prospect's email               |
| **Job title**       | Prospect's job title           |
| **Company domain**  | Company domain                 |
| **Runtime context** | Additional context             |

### Qualify company

Score and qualify companies.

**Configuration**

| Field               | Description                     |
| ------------------- | ------------------------------- |
| **Agent**           | Select a QUALIFY\_COMPANY agent |
| **Company domain**  | Company domain                  |
| **Company name**    | Company name                    |
| **Runtime context** | Additional context              |

### Prospector

Find contacts at a target company.

**Configuration**

| Field              | Description                       |
| ------------------ | --------------------------------- |
| **Agent**          | Select a PROSPECTOR agent         |
| **Company domain** | Company domain (required)         |
| **Limit**          | Override agent's configured limit |
| **Search context** | Override agent's search context   |

### Generate content

Generate personalized content for prospects.

**Configuration**

| Field               | Description               |
| ------------------- | ------------------------- |
| **Agent**           | Select a CONTENT agent    |
| **Email**           | Prospect's email          |
| **URL**             | Reference URL for content |
| **Runtime context** | Additional context        |

### Enrich person / Enrich company

Enrich prospect or company data using AI research.

### Call preparation

Generate call prep materials for sales calls.

***

## Use cases

<AccordionGroup>
  <Accordion title="Email personalization" icon="envelope">
    Generate personalized email sequences at scale.
  </Accordion>

  <Accordion title="Lead qualification" icon="filter">
    Score leads based on AI-powered research.
  </Accordion>

  <Accordion title="Prospecting" icon="users">
    Find the right contacts at target accounts.
  </Accordion>

  <Accordion title="Call prep" icon="phone">
    Generate briefings before sales calls.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Configure agents in Octave** - Set up agent templates in Octave dashboard first
2. **Use runtime context** - Provide additional context for better personalization
3. **Match agent types** - Use the right agent type for each action


# OneSignal
Source: https://docs.getcargo.ai/integration/onesignal

Connect OneSignal to send SMS messages in your workflows.

## How to set up OneSignal

### Authentication

OneSignal requires App credentials:

1. Log in to your OneSignal account
2. Navigate to **Settings** → **Keys & IDs**
3. Obtain your credentials:
   * **App ID**: Your OneSignal App ID
   * **REST API Key**: Your REST API key
4. Enter both in Cargo when connecting

## OneSignal actions

### Send SMS

Send an SMS message using OneSignal's messaging platform.

**Required fields:**

* **SMS Identifier**: Tracking identifier for the message
* **From**: Sending phone number (Twilio number in E.164 format)
* **To**: Recipient phone number
* **Content**: SMS message content (supports expressions)

**Optional fields:**

* **Media URLs**: Attach media to the message (MMS)

## Message formatting

SMS content supports dynamic expressions:

```
Hi {{first_name}}, your order {{order_id}} has shipped!
Track it here: {{tracking_url}}
```

## Example messages

### Appointment reminder:

```
Hi {{first_name}}, this is a reminder of your appointment 
tomorrow at {{time}}. Reply CONFIRM to confirm or call 
us to reschedule.
```

### Welcome message:

```
Welcome to {{company_name}}, {{first_name}}! Your account 
is ready. Get started: {{onboarding_url}}
```

### Alert notification:

```
🔔 {{alert_type}}: {{message}}
View details: {{dashboard_url}}
```

## E.164 phone format

Phone numbers must be in E.164 format:

| Country | Format        | Example       |
| ------- | ------------- | ------------- |
| US      | +1XXXXXXXXXX  | +14155551234  |
| UK      | +44XXXXXXXXXX | +442071234567 |
| France  | +33XXXXXXXXX  | +33123456789  |

## Best practices

* Use unique SMS identifiers for tracking
* Keep messages concise (SMS has 160 character limit)
* Include clear call-to-action
* Respect opt-out preferences
* Use MMS for rich media when appropriate
* Test phone number formatting before campaigns

## Compliance

* Ensure recipients have opted in to SMS
* Include opt-out instructions when required
* Follow local SMS regulations (TCPA, GDPR, etc.)
* Respect quiet hours for non-urgent messages

## Use cases

* **Transactional alerts**: Order updates, shipping notifications
* **Reminders**: Appointments, renewals, deadlines
* **Engagement**: Welcome messages, re-engagement
* **Support**: Ticket updates, resolution notices
* **Sales**: Direct outreach, meeting reminders


# OpenAI
Source: https://docs.getcargo.ai/integration/open-ai

This page outlines how to use the OpenAI integration for AI-powered actions in Cargo.

OpenAI provides advanced language models that power intelligent automation. Cargo's native integration with OpenAI allows you to use GPT models directly in your workflows for text generation, classification, summarization, and more.

## How to set up OpenAI

You can use OpenAI in two ways:

1. **Cargo credits** – Use OpenAI through Cargo's managed integration (no API key required)
2. **Your own API key** – Connect your OpenAI account for direct access

### Using Cargo credits

Select OpenAI from the node catalog and start using it immediately. Costs are deducted from your Cargo credits based on token usage.

### Using your own API key

To connect your OpenAI account:

| Field       | Description         |
| ----------- | ------------------- |
| **API Key** | Your OpenAI API key |

<Tip>
  Find your API key in the OpenAI platform under **API keys**.
</Tip>

***

## OpenAI actions

### Instruct

Send a prompt to an OpenAI model and receive a text response.

**Use cases**

* **Content generation** – Generate personalized emails, messages, or content
* **Classification** – Categorize text into predefined categories
* **Summarization** – Summarize long text into concise summaries
* **Data extraction** – Extract structured data from unstructured text
* **Translation** – Translate text between languages
* **Analysis** – Analyze sentiment, intent, or other text properties

**Configuration**

| Field               | Description                                             |
| ------------------- | ------------------------------------------------------- |
| **Model**           | Select the GPT model to use                             |
| **Prompt**          | The prompt to send to the model                         |
| **System prompt**   | Optional system instructions                            |
| **Maximum tokens**  | Limit output length (includes reasoning tokens)         |
| **Temperature**     | Control randomness (0 = deterministic, 2 = very random) |
| **With web search** | Enable web search capabilities for the agent            |
| **Response format** | Text, JSON object, or JSON schema                       |

### Available models

The available models — and their per-model credit costs — evolve with OpenAI's lineup, so the action's **Model** dropdown in the workspace is always the authoritative list. From the terminal:

```bash theme={null}
cargo-ai connection integration get openAi
```

**Picking a model:**

* **Flagship models** — complex reasoning, multi-step analysis, coding tasks
* **Mini variants** — the best cost/performance balance for most everyday tasks (start here)
* **Nano variants** — high-volume, low-stakes work: summarization, classification, simple extraction

### Response formats

Control how the model returns its response:

| Format          | Description                                       |
| --------------- | ------------------------------------------------- |
| **Text**        | Free-form text response (default)                 |
| **JSON object** | Response formatted as valid JSON                  |
| **JSON schema** | Response validated against a specific JSON schema |

<Tip>
  Use **JSON schema** when you need structured output with specific fields.
  Define your schema to ensure consistent, parseable responses.
</Tip>

#### Example JSON schema

```json theme={null}
{
  "type": "object",
  "properties": {
    "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
    "confidence": { "type": "number" },
    "summary": { "type": "string" }
  },
  "additionalProperties": false,
  "required": ["sentiment", "confidence", "summary"]
}
```

### Advanced settings

#### System prompt

Set instructions that guide the model's behavior across all prompts. Use system prompts to:

* Define the model's role or persona
* Set output format guidelines
* Provide context about your use case
* Establish constraints or rules

#### Temperature

Control the randomness of outputs:

| Temperature | Behavior                               |
| ----------- | -------------------------------------- |
| **0**       | Most deterministic, consistent outputs |
| **0.5-1**   | Balanced creativity and consistency    |
| **1-2**     | More creative, varied outputs          |

<Warning>
  For tasks requiring consistency (classification, extraction), use low
  temperature (0-0.3). For creative tasks (content generation), use higher
  temperature (0.7-1).
</Warning>

#### Web search

Enable the model to search the web for current information. Useful for:

* Real-time data lookups
* Current events or news
* Company or product research
* Fact verification


# Outreach
Source: https://docs.getcargo.ai/integration/outreach

This page outlines how to use the Outreach integration to manage sales engagement in Cargo.

Outreach is a leading sales engagement platform that helps sales teams close more deals through automated sequences, personalized outreach, and actionable insights. Cargo's native integration with Outreach allows you to manage prospects, accounts, and sequences directly from your workflows.

## How to set up Outreach

Outreach uses OAuth to establish the connection with Cargo. During connection, you'll be redirected to Outreach to authorize Cargo.

Once the connector is created, you can:

* **Set up an Outreach data model** — Create data models from your Outreach accounts, prospects, or events to trigger Plays and power model search actions.
* **Use Outreach in workflows** — Choose **Outreach** from the node catalog within a **Play**, **Tool**, or **Agent**.

***

## Outreach actions

<Tip>
  Outreach actions support Accounts and Prospects, allowing you to manage your
  sales pipeline directly from Cargo workflows.
</Tip>

### Get record

Retrieve a single record from Outreach by its ID.

**Use cases**

* **Data lookup** – Fetch prospect or user details for use in workflows
* **Conditional logic** – Retrieve record data to make routing decisions

**Configuration**

| Field           | Description                               |
| --------------- | ----------------------------------------- |
| **Object type** | Select User or Prospect                   |
| **ID**          | The Outreach ID of the record to retrieve |

### Insert record

Create a new record in Outreach.

**Use cases**

* **Lead creation** – Add new prospects from inbound sources
* **Account creation** – Create accounts for companies in your pipeline
* **Data sync** – Push records from other systems to Outreach

**Configuration**

| Field           | Description                       |
| --------------- | --------------------------------- |
| **Object type** | Select Account or Prospect        |
| **Mappings**    | Map Outreach properties to values |

### Upsert records

Create new records or update existing ones based on a matching property.

**Use cases**

* **Bulk data sync** – Sync records from your CRM or data warehouse
* **Avoid duplicates** – Insert new records only if they don't already exist
* **Data enrichment** – Update existing records with enriched information

**Configuration**

| Field                      | Description                       |
| -------------------------- | --------------------------------- |
| **Object type**            | Select Account or Prospect        |
| **Matching Property Name** | The Outreach property to match on |
| **Matching Value**         | The value to match against        |
| **Mappings**               | Map Outreach properties to values |

<Info>
  The upsert operation will search for existing records matching your criteria.
  If a match is found, the record is updated; otherwise, a new record is created.
</Info>

### Update records

Update existing records in Outreach that match specified criteria.

**Use cases**

* **Data enrichment** – Update prospects with enriched contact information
* **Status updates** – Update prospect stages based on workflow conditions
* **Field updates** – Bulk update specific fields across matching records

**Configuration**

| Field                      | Description                           |
| -------------------------- | ------------------------------------- |
| **Object type**            | Select Account or Prospect            |
| **Matching Property Name** | The Outreach property to match on     |
| **Matching Value**         | The value to match against            |
| **Mappings**               | Map Outreach properties to new values |

### Delete records

Delete records from Outreach that match specified criteria.

**Use cases**

* **Data cleanup** – Remove outdated or invalid records
* **GDPR compliance** – Delete prospect data upon request
* **Pipeline hygiene** – Remove prospects that no longer qualify

**Configuration**

| Field                      | Description                       |
| -------------------------- | --------------------------------- |
| **Object type**            | Select Account or Prospect        |
| **Matching Property Name** | The Outreach property to match on |
| **Matching Value**         | The value to match against        |

<Warning>
  Deleting records is permanent. Ensure your matching criteria is correct before
  executing this action.
</Warning>

### Add to sequence

Add a prospect to an Outreach sequence for automated follow-up.

**Use cases**

* **Sales outreach** – Automatically enroll qualified leads in nurture sequences
* **Re-engagement** – Add cold prospects to re-engagement sequences
* **Onboarding** – Enroll new customers in onboarding sequences

**Configuration**

| Field                      | Description                                |
| -------------------------- | ------------------------------------------ |
| **Sequence**               | Select the sequence to add the prospect to |
| **Mailbox**                | Select the mailbox to send from            |
| **Matching Property Name** | The property to match the prospect on      |
| **Matching Value**         | The value to identify the prospect         |

<Tip>
  Make sure the prospect exists in Outreach before adding them to a sequence.
  Use the **Upsert records** action first if needed.
</Tip>

### Associate records

Create an association between a prospect and an account.

**Use cases**

* **Account mapping** – Link prospects to their company accounts
* **Territory management** – Associate prospects with the correct accounts
* **Relationship tracking** – Maintain prospect-account relationships

**Configuration**

| Field                | Description                             |
| -------------------- | --------------------------------------- |
| **From Object Type** | Prospect                                |
| **From Object ID**   | The ID of the prospect to associate     |
| **To Object Type**   | Account                                 |
| **To Object ID**     | The ID of the account to associate with |

***

## Outreach data models

Cargo allows you to create data models on top of your Outreach data that can be used to trigger Plays and power model search actions.

### Available extractors

<AccordionGroup>
  <Accordion title="Fetch accounts" icon="building">
    Pull account records from Outreach with incremental sync support.

    **Use cases**

    * Build data models from your Outreach accounts
    * Trigger workflows when accounts are created or updated
  </Accordion>

  <Accordion title="Fetch prospects" icon="user">
    Pull prospect records from Outreach with incremental sync support.

    **Use cases**

    * Build data models from your Outreach prospects
    * Trigger workflows based on prospect changes
  </Accordion>

  <Accordion title="Fetch events" icon="calendar">
    Pull engagement events from Outreach including calls, mailings, tasks, and meetings.

    **Use cases**

    * Track sales engagement activities
    * Trigger workflows based on prospect interactions
  </Accordion>
</AccordionGroup>


# Overview
Source: https://docs.getcargo.ai/integration/overview

Connect Cargo to your entire go-to-market stack

Cargo integrates with 130+ tools across your sales, marketing, and operations stack. Connect your CRM, enrichment providers, outreach platforms, and data warehouses, then use their actions from your [workflows](/workflows/overview) and [models](/models/overview).

Every integration is a [connector](/connectors/overview) you define in code:

```ts connectors/hubspot.ts theme={null}
import { defineConnector, secret } from "@cargo-ai/cdk";

export const hubspot = defineConnector("hubspot", {
  integration: "hubspot",
  config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
});
```

Then call its actions in a workflow (`integrations.hubspot.<action>(...)`) or pull its data into a model (`extractSlug`). Each connector page below documents the actions available and shows all three patterns.

<Info>
  **Need to connect a tool that's not listed?** You can build your own [custom
  integration](/integration/custom-integration) to connect any API to Cargo.
</Info>

***

## Integration categories

<CardGroup>
  <Card title="CRM & Sales" icon="handshake" href="#crm--sales-platforms">
    Sync data with your CRM and sales platforms
  </Card>

  <Card title="Sales Engagement" icon="paper-plane" href="#sales-engagement">
    Automate outreach sequences and campaigns
  </Card>

  <Card title="Enrichment" icon="sparkles" href="#contact--company-enrichment">
    Enrich contacts and companies with data
  </Card>

  <Card title="Email & Phone" icon="envelope-circle-check" href="#email-finder--verification">
    Find and verify contact information
  </Card>

  <Card title="AI & LLM" icon="brain" href="#ai--llm">
    Leverage AI models in your workflows
  </Card>

  <Card title="Data & Analytics" icon="database" href="#data--analytics">
    Connect warehouses and analytics platforms
  </Card>
</CardGroup>

***

## CRM & Sales platforms

Connect your CRM to sync data bidirectionally—pull records into Cargo workflows and push enriched data back.

| Integration                           | Description                                      |
| ------------------------------------- | ------------------------------------------------ |
| [Salesforce](/integration/salesforce) | Enterprise CRM with full CRUD operations         |
| [HubSpot](/integration/hubspot)       | All-in-one CRM for marketing, sales, and service |
| [Pipedrive](/integration/pipedrive)   | Sales-focused CRM with pipeline management       |
| [Close](/integration/closecom)        | CRM built for inside sales teams                 |
| [Attio](/integration/attio)           | Flexible CRM with relationship intelligence      |
| [NetSuite](/integration/netsuite)     | Oracle's cloud ERP with CRM capabilities         |
| [Marketo](/integration/marketo)       | Marketing automation — custom object CRUD        |
| [Intercom](/integration/intercom)     | Customer messaging platform with contact sync    |

***

## Sales engagement

Automate multi-channel outreach and manage sequences across email and LinkedIn.

| Integration                               | Description                                |
| ----------------------------------------- | ------------------------------------------ |
| [Outreach](/integration/outreach)         | Enterprise sales engagement platform       |
| [Salesloft](/integration/salesloft)       | Revenue workflow platform with sequences   |
| [Apollo.io](/integration/apolloio)        | Sales intelligence and engagement platform |
| [Lemlist](/integration/lemlist)           | Email outreach with personalization        |
| [Instantly](/integration/instantly)       | Cold email at scale (Legacy)               |
| [Instantly V2](/integration/instantly-v2) | Next-gen cold email platform               |
| [Smartlead](/integration/smartlead)       | AI-powered cold email infrastructure       |
| [Email Bison](/integration/email-bison)   | Cold email sending platform                |
| [LaGrowthMachine](/integration/lgm)       | Multi-channel sales automation             |
| [Snov.io](/integration/snov)              | Email finder and drip campaigns            |
| [HeyReach](/integration/hey-reach)        | LinkedIn automation at scale               |
| [Expandi](/integration/expandi)           | LinkedIn outreach automation               |
| [Amplemarket](/integration/amplemarket)   | AI-powered sales engagement                |
| [Rift](/integration/rift)                 | Revenue intelligence platform              |

***

## Contact & Company enrichment

Enrich your leads and accounts with firmographic, technographic, and contact data.

| Integration                                       | Description                                                         |
| ------------------------------------------------- | ------------------------------------------------------------------- |
| [Cargo](/integration/cargo)                       | Native B2B data — sourcing, matching, enrichment, and event signals |
| [Clearbit](/integration/clearbit)                 | Real-time company and contact enrichment                            |
| [ZoomInfo](/integration/zoominfo)                 | B2B database with intent data                                       |
| [People Data Labs](/integration/people-data-labs) | Person and company data API                                         |
| [Cognism](/integration/cognism)                   | GDPR-compliant B2B data provider                                    |
| [Lusha](/integration/lusha)                       | Contact and company data platform                                   |
| [LeadMagic](/integration/lead-magic)              | B2B data enrichment service                                         |
| [Kaspr](/integration/kaspr)                       | LinkedIn data extraction                                            |
| [ContactOut](/integration/contact-out)            | Email finder for LinkedIn profiles                                  |
| [Dropcontact](/integration/dropcontact)           | B2B email finder and enrichment                                     |
| [Datagma](/integration/datagma)                   | B2B contact and company enrichment                                  |
| [ReverseContact](/integration/reverse-contact)    | Email-to-profile enrichment                                         |
| [ProxyCurl](/integration/proxycurl)               | LinkedIn profile data API                                           |
| [Ocean.io](/integration/oceanio)                  | Lookalike company discovery                                         |
| [Coresignal](/integration/coresignal)             | Professional network data                                           |
| [Store Leads](/integration/storeleads)            | E-commerce store intelligence                                       |
| [Societe Info](/integration/societe-info)         | French company data provider                                        |
| [Waterfall](/integration/waterfall)               | Contact enrichment cascade                                          |
| [Mixrank](/integration/mixrank)                   | Mobile app and SDK intelligence                                     |
| [EnrichCRM](/integration/enrich-crm)              | CRM enrichment service                                              |
| [Forager](/integration/forager)                   | Contact finding service                                             |
| [Company Enrich](/integration/company-enrich)     | Company data enrichment                                             |
| [FullEnrich](/integration/full-enrich)            | Waterfall enrichment platform                                       |
| [Surfe](/integration/surfe)                       | People and company search and enrichment                            |
| [Airscale](/integration/airscale)                 | People search, phone, and email lookup                              |

***

## Email finder & verification

Find email addresses and verify deliverability to maintain list hygiene.

| Integration                                   | Description                      |
| --------------------------------------------- | -------------------------------- |
| [Hunter](/integration/hunter)                 | Domain email finder and verifier |
| [Findymail](/integration/findy-mail)          | Email finder with verification   |
| [Anymail Finder](/integration/anymail-finder) | Email discovery service          |
| [Icypeas](/integration/icypeas)               | Email finder and verifier        |
| [BetterContact](/integration/bettercontact)   | Waterfall email finder           |
| [Wiza](/integration/wiza)                     | LinkedIn email extraction        |
| [Prospeo](/integration/prospeo)               | Email finder and domain search   |
| [NeverBounce](/integration/never-bounce)      | Email verification service       |
| [ZeroBounce](/integration/zero-bounce)        | Email validation and scoring     |
| [Bouncer](/integration/bouncer)               | Email verification API           |
| [BounceBan](/integration/bounceban)           | Accept-all email verification    |
| [Enrow.io](/integration/enrowio)              | Email finder and verifier        |
| [Scrubby](/integration/scrubby)               | Catch-all email verification     |
| [Enrichley](/integration/enrichley)           | Email verification service       |
| [Theneo](/integration/theneo)                 | Email verification               |
| [Kitt](/integration/kitt)                     | Email verification API           |

***

## Phone verification

Validate phone numbers for deliverability and accuracy.

| Integration                                  | Description                     |
| -------------------------------------------- | ------------------------------- |
| [ClearoutPhone](/integration/clearout-phone) | Phone number validation service |
| [Cleon1](/integration/cleon1)                | Phone discovery from LinkedIn   |

***

## AI & LLM

Leverage large language models to generate content, analyze data, and power agents.

| Integration                                | Description                            |
| ------------------------------------------ | -------------------------------------- |
| [OpenAI](/integration/open-ai)             | GPT models for generation and analysis |
| [Azure OpenAI](/integration/azure-open-ai) | OpenAI models on Azure infrastructure  |
| [Anthropic](/integration/anthropic)        | Claude models for complex reasoning    |
| [Google Gemini](/integration/gemini)       | Google's multimodal AI models          |
| [Perplexity](/integration/perplexity)      | AI-powered research and search         |
| [DeepSeek](/integration/deep-seek)         | Open-source reasoning models           |
| [Octave](/integration/octave)              | AI-powered sales intelligence          |
| [PromptLayer](/integration/prompt-layer)   | LLM prompt management and versioning   |
| [Manus](/integration/manus)                | AI agent task execution                |
| [Devin](/integration/devin)                | AI software engineer for coding tasks  |
| [Replicas](/integration/replicas)          | Cloud workspaces for coding agents     |

***

## Data & Analytics

Connect your data warehouse and analytics platforms to power data models and syncs.

| Integration                               | Description                              |
| ----------------------------------------- | ---------------------------------------- |
| [Snowflake](/integration/snowflake)       | Cloud data warehouse                     |
| [BigQuery](/integration/big-query)        | Google's serverless data warehouse       |
| [Redshift](/integration/redshift)         | AWS cloud data warehouse                 |
| [PostgreSQL](/integration/postgresql)     | PostgreSQL database connection           |
| [SQL](/integration/sql)                   | Custom SQL queries against warehouses    |
| [dbt](/integration/dbt)                   | Data transformation and modeling         |
| [Metabase](/integration/metabase)         | Business intelligence and SQL queries    |
| [Mixpanel](/integration/mixpanel)         | Product analytics platform               |
| [Amplitude](/integration/amplitude)       | Product analytics and engagement         |
| [6sense](/integration/6sense)             | Account-based marketing intelligence     |
| [LinkedIn Ads](/integration/linkedin-ads) | LinkedIn advertising analytics           |
| [Google Ads](/integration/google-ads)     | Google Ads audiences and conversions     |
| [Adyntel](/integration/adyntel)           | Ad library intelligence across platforms |
| [Appfigures](/integration/appfigures)     | App store analytics and intelligence     |

***

## Intent & Visitor identification

Identify website visitors and track buying intent signals.

| Integration                                | Description                           |
| ------------------------------------------ | ------------------------------------- |
| [Albacross](/integration/albacross)        | Website visitor identification        |
| [RB2B](/integration/rb2b)                  | Person-level website visitor tracking |
| [Snitcher](/integration/snitcher)          | Website visitor intelligence          |
| [PredictLeads](/integration/predict-leads) | Hiring and technology signals         |
| [Datachimp](/integration/datachimp)        | Job posting and hiring signals        |
| [Sumble](/integration/sumble)              | Technology usage and hiring intent    |

***

## Web scraping & Research

Scrape websites, search the web, and gather competitive intelligence.

| Integration                                 | Description                                       |
| ------------------------------------------- | ------------------------------------------------- |
| [Firecrawl](/integration/firecrawl)         | Web scraping with AI extraction                   |
| [Apify](/integration/apify)                 | Run Apify actors for web scraping                 |
| [Exa](/integration/exa)                     | AI-native semantic web search                     |
| [Serper](/integration/serper)               | Google search API                                 |
| [Captain Data](/integration/captain-data)   | No-code web scraping platform                     |
| [Piloterr](/integration/piloterr)           | Company technographics                            |
| [Linkup](/integration/linkup)               | Deep web search engine                            |
| [Bright Data](/integration/bright-data)     | Social profile scraping (Instagram, TikTok, X, …) |
| [Phantombuster](/integration/phantombuster) | Launch Phantoms and sync their results            |
| [Parallel](/integration/parallel)           | AI web search, extraction, and research tasks     |

***

## LinkedIn & Social

Access LinkedIn data and automate social selling workflows.

| Integration                                                         | Description                           |
| ------------------------------------------------------------------- | ------------------------------------- |
| [LinkedIn](/integration/linkedin)                                   | Professional network integration      |
| [Sales Navigator](/integration/sales-navigator)                     | Advanced LinkedIn sales intelligence  |
| [LinkedIn Matched Audience](/integration/linkedin-matched-audience) | Sync audiences to LinkedIn Ads        |
| [TheSwarm](/integration/the-swarm)                                  | Warm intro discovery through networks |
| [GitHub](/integration/github)                                       | Developer profiles and repositories   |

***

## Communication & Messaging

Send messages across channels and sync communication data.

| Integration                                     | Description                      |
| ----------------------------------------------- | -------------------------------- |
| [Slack](/integration/slack)                     | Team messaging and notifications |
| [Microsoft Teams](/integration/microsoft-teams) | Enterprise team collaboration    |
| [SendGrid](/integration/sendgrid)               | Transactional email delivery     |
| [Resend](/integration/resend)                   | Transactional email API          |
| [OneSignal](/integration/onesignal)             | Push notifications and messaging |
| [Customer.io](/integration/customerio)          | Marketing automation messaging   |

***

## MCP connectors

Connect a provider's hosted MCP server so [agents](/agents/tools-and-actions#mcp-servers) can call its tools — discovered from the server at runtime.

| Integration                                   | Description                                |
| --------------------------------------------- | ------------------------------------------ |
| [HubSpot MCP](/integration/hubspot-mcp)       | HubSpot's MCP server for agents            |
| [Salesforce MCP](/integration/salesforce-mcp) | Salesforce's per-org MCP server for agents |
| [Notion MCP](/integration/notion-mcp)         | Notion's MCP server for agents             |

***

## Events & Scheduling

Manage events, webinars, and scheduling integrations.

| Integration                         | Description                           |
| ----------------------------------- | ------------------------------------- |
| [Calendly](/integration/calendly)   | Scheduling and calendar automation    |
| [Livestorm](/integration/livestorm) | Video engagement and webinar platform |
| [Contrast](/integration/contrast)   | Event registration and management     |

***

## Project management

Connect productivity and project management tools.

| Integration               | Description                           |
| ------------------------- | ------------------------------------- |
| [Jira](/integration/jira) | Issue tracking and project management |

***

## Payments & Billing

Sync payment and subscription data.

| Integration                   | Description                              |
| ----------------------------- | ---------------------------------------- |
| [Stripe](/integration/stripe) | Payment processing and subscription data |

***

## Other integrations

Additional specialized integrations for specific use cases.

| Integration                                 | Description                                |
| ------------------------------------------- | ------------------------------------------ |
| [RSS Feed](/integration/rss-feed)           | Subscribe to RSS feeds for content updates |
| [HTTP](/integration/http)                   | Custom HTTP requests to any API            |
| [Google Sheets](/integration/google-sheets) | Spreadsheet data sync                      |
| [CSV](/integration/csv)                     | Turn uploaded CSV files into data models   |
| [TheirStack](/integration/their-stack)      | Technology stack intelligence              |
| [G2](/integration/g2)                       | Software reviews and buyer intent          |
| [Rocketreach](/integration/rocketreach)     | Contact and company data                   |
| [SalesIntel](/integration/sales-intel)      | B2B data and buying signals                |

***

## Getting started

<Steps>
  <Step title="Define the connector">
    Add a `defineConnector` file with `secret()` credentials (or `cargo-ai project add connector/<slug>`
    for an OAuth connector), then `cargo-ai project deploy`. See
    [Connectors](/connectors/overview).
  </Step>

  <Step title="Model the data (optional)">
    For CRM and data integrations, add a `defineModel` with an `extractSlug` to
    sync records into Cargo. These power play triggers and model search. See
    [Extractors](/models/extractors).
  </Step>

  <Step title="Use the actions">
    Call `uses.<key>.<action>()` from a [workflow](/workflows/overview), or
    reference `connector.actions.<slug>` in an [agent](/agents/overview)'s `uses`.
  </Step>
</Steps>

<Tip>
  Prefer the UI? Navigate to **Settings → Integrations → Add connection** and
  follow the auth flow. Connectors created in the app are bound into code by slug,
  or with `default: true`. Most integrations support multiple authentication methods.
</Tip>


# Parallel
Source: https://docs.getcargo.ai/integration/parallel

Connect Parallel AI for web search, content extraction, and deep research tasks in your workflows.

## How to set up Parallel

### Authentication

Parallel runs on Cargo credits out of the box, so you can use it without a Parallel account. To bill Parallel directly instead, connect your own API key:

1. Sign up at [parallel.ai](https://parallel.ai)
2. Create an API key in your Parallel dashboard
3. Paste the API key in Cargo when connecting

<Note>
  **Code slugs** — integration slug: `parallel` · actions: `search`, `extract`, `createTask`. In a [workflow](/workflows/overview), declare the connector in `uses` and call `uses.<key>.search(...)`.
</Note>

## Parallel actions

### Search

Search the web with Parallel AI and return ranked results with relevant excerpts.

**Required fields:**

* **Search queries**: Concise keyword queries, 3-6 words each; provide 2-3 for best results

**Optional fields:**

* **Objective**: Natural-language description of the question or goal driving the search
* **Search mode**: `basic` for lowest latency, `advanced` for higher quality (default)
* **Number of results**: Maximum results to return (1-100)
* **Max characters total**: Upper bound on total characters across excerpts
* **Include domains**: Only return results from these domains (accepts `.gov`-style extensions)
* **Exclude domains**: Exclude results from these domains
* **After date**: Only include results published on or after this date (YYYY-MM-DD)

**Use case:** Find recent news, funding announcements, or public signals about an account before outreach.

### Extract

Extract relevant content from specific web URLs.

**Required fields:**

* **URLs**: URLs to extract content from (up to 20)

**Optional fields:**

* **Objective**: Natural-language goal used to focus excerpts on the most relevant content
* **Search queries**: Keyword queries used together with the objective to focus excerpts
* **Max characters total**: Upper bound on total characters across extracted excerpts
* **Include full content**: Also return the full page content as markdown

**Use case:** Pull pricing, careers, or product details from known pages of a prospect's website for enrichment.

### Create Task

Execute a full web research task — complex queries that require deep research, analysis, and structured output. The task runs asynchronously on Parallel's side and the workflow resumes when it completes (up to 60 minutes).

**Required fields:**

* **Input**: A natural-language question or a description of what to research
* **Processor**: `lite`, `base`, `core` (balanced, default), `core2x`, `pro`, `ultra`, `ultra2x`, `ultra4x`, or `ultra8x` — from fastest and cheapest to deepest and most expensive

**Optional fields:**

* **Output schema**: Description of the desired output — natural language or a JSON schema as a string
* **Include domains**: Only use results from these domains
* **Exclude domains**: Exclude results from these domains
* **After date**: Only include results published on or after this date (YYYY-MM-DD)
* **Location**: ISO 3166-1 alpha-2 country code for geo-targeted results (e.g., `us`, `gb`)

The result includes the task output, output metadata (citations and confidence), and the sources used.

**Use case:** Research an entire account — business model, ICP fit, recent initiatives — and return it as a structured object for scoring.

## Best practices

* Use Search for quick lookups and Create Task for research that needs synthesis across many sources
* Give Create Task an output schema to get structured, mappable results instead of free text
* Scope searches with include/exclude domains and an after date to cut noise and stale results
* Pick the cheapest processor that does the job: `lite` or `base` for simple lookups, the `ultra` tiers only for genuinely complex questions — each step up the ladder multiplies the credit cost
* Cap **Number of results** on Search: the first 10 come with the request, and every result past that adds to the bill
* Account for Create Task's asynchronous nature (up to 60 minutes) when designing time-sensitive workflows

## Credits

Parallel is billable with Cargo credits, so you can use it without your own Parallel account. Costs mirror Parallel's published pricing at \$0.04 per Cargo credit.

* **Search**: 0.125 credits per search, which covers the first 10 results, plus 0.025 credits for each additional result returned
* **Extract**: 0.025 credits per URL submitted, whether or not the page could be read
* **Create Task**: a flat cost per run that depends on the processor

| Processor | Credits per task |
| --------- | ---------------- |
| `lite`    | 0.125            |
| `base`    | 0.25             |
| `core`    | 0.625            |
| `core2x`  | 1.25             |
| `pro`     | 2.5              |
| `ultra`   | 7.5              |
| `ultra2x` | 15               |
| `ultra4x` | 30               |
| `ultra8x` | 60               |

Cargo tracks credit usage and supports caching to optimize costs.

## Rate limits

Parallel rate-limits each endpoint separately, and only counts the requests that create work — retrieving a task result is free. Cargo spreads calls to stay under the limits and retries on rejection.

* **Search**: 600 requests per minute
* **Extract**: 600 requests per minute
* **Create Task**: 2,000 task runs per minute

On Cargo credits these limits are shared across all workspaces on Cargo's key; on your own API key they apply to your connector alone.


# People Data Labs
Source: https://docs.getcargo.ai/integration/people-data-labs

Connect People Data Labs for comprehensive person and company data enrichment and search.

## How to set up People Data Labs

### Authentication

People Data Labs uses API key authentication:

1. Sign up at [peopledatalabs.com](https://peopledatalabs.com)
2. Navigate to your API dashboard
3. Copy your API key
4. Paste the API key in Cargo when connecting

## People Data Labs actions

### Enrich person

Get comprehensive profile data for a person.

**Input parameters (provide as many as available):**

* **Name / First name / Last name**: Person's name
* **Email / Email hash**: Email address
* **Phone**: Phone number
* **Company / School**: Employment or education
* **Profile / LinkedIn ID**: Social profile URL or ID
* **Location / Country / Region**: Geographic data
* **PDL ID**: People Data Labs ID (if known)

**Options:**

* **Data include**: Select specific fields to return
* **Min likelihood**: Minimum confidence threshold
* **Titlecase**: Return titlecased text

**Credits:** 3 credits per request

### Enrich company

Get detailed company information.

**Input parameters:**

* **PDL ID**: People Data Labs company ID
* **Name**: Company name
* **Website / Profile**: Company website or LinkedIn
* **Ticker**: Stock ticker symbol
* **Location details**: Address, city, region, country

**Credits:** 3 credits per request

### Search people

Find people matching specific criteria using filters.

**Configuration:**

* **Filter**: Build complex filter conditions
* **Limit**: Maximum results to return
* **Titlecase / Pretty**: Output formatting

**Credits:** 3 credits per result

### Search companies

Find companies matching specific criteria.

**Configuration:**

* **Filter**: Build filter conditions
* **Limit**: Maximum results to return

**Credits:** 3 credits per result

### Query people

Search people using SQL-like queries.

**Required fields:**

* **Query**: SQL query (e.g., `SELECT * FROM people WHERE ...`)
* **Limit**: Maximum results

**Credits:** 3 credits per result

**Use case:** Complex queries with full SQL flexibility.

### Query companies

Search companies using SQL-like queries.

**Required fields:**

* **Query**: SQL query for companies
* **Limit**: Maximum results

**Credits:** 3 credits per result

## People Data Labs data models

### Fetch people

Pull people matching criteria into Cargo.

**Configuration:**

* **Filter**: Define matching criteria
* **Limit**: Maximum records

**Features:**

* Unifies contacts by email, LinkedIn ID
* Credits charged per result

### Fetch companies

Pull companies matching criteria into Cargo.

**Configuration:**

* **Filter**: Define matching criteria
* **Limit**: Maximum records

**Features:**

* Unifies accounts by domain, LinkedIn
* Credits charged per result

## Credits summary

| Action           | Credits      |
| ---------------- | ------------ |
| Enrich person    | 3 (fixed)    |
| Enrich company   | 3 (fixed)    |
| Search people    | 3 per result |
| Search companies | 3 per result |
| Query people     | 3 per result |
| Query companies  | 3 per result |
| Fetch people     | 3 per result |
| Fetch companies  | 3 per result |

## Rate limits

People Data Labs API has a rate limit of 100 requests per minute. Cargo handles rate limiting automatically.

## Best practices

* Provide multiple identifiers for better matching
* Use min\_likelihood to filter low-confidence matches
* Start with search to find IDs, then enrich for full data
* Use SQL queries for complex, custom filtering
* Cache enrichment results to avoid duplicate lookups


# Perplexity
Source: https://docs.getcargo.ai/integration/perplexity

Connect Perplexity AI to leverage internet-connected AI models for research and analysis in your workflows.

## How to set up Perplexity

### Authentication

Perplexity uses API key authentication:

1. Sign up at [perplexity.ai](https://perplexity.ai)
2. Navigate to API settings
3. Generate an API key
4. Copy the API key and paste it in Cargo when connecting

## Perplexity actions

### Instruct

Use Perplexity's AI models to generate responses with real-time internet access.

**Required fields:**

* **Model**: Select the AI model
* **Prompt**: Your instruction or question

**Available models:**

| Model               | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| Sonar Deep Research | Comprehensive expert-level research synthesized into actionable reports |
| Sonar               | Lightweight search-grounded model, faster and cheaper                   |
| Sonar Pro           | Premier search offering for advanced queries and follow-ups             |
| Sonar Reasoning     | Reasoning model powered by DeepSeek R1 with Chain of Thought            |
| Sonar Reasoning Pro | Enhanced reasoning with Chain of Thought capabilities                   |

**Advanced settings:**

* **Search Context Size**: Controls search depth (High, Medium, Low)
* **System prompt**: Set context for the model's behavior
* **Search recency filter**: Limit results to month, week, day, or hour
* **Search domain filter**: Whitelist or blacklist specific domains (prefix with `-` to blacklist)
* **Return related questions**: Get suggested follow-up questions
* **Return images**: Include relevant images in responses
* **Maximum tokens**: Limit response length
* **Temperature**: Control response randomness (0-2)

**Output options:**

* **Text**: Plain text response
* **JSON schema**: Structured JSON output matching your schema
* **Regex**: Response matching a regex pattern

## Use cases

* **Account research**: Deep-dive into target accounts before outreach
* **Lead enrichment**: Supplement traditional enrichment with real-time web data
* **Content generation**: Create personalized content based on research
* **News monitoring**: Track company and industry news
* **Due diligence**: Research potential partners or acquisition targets

## Credits and pricing

Perplexity uses token-based pricing that varies by model and search context:

| Model               | Context | Cost per 1K tokens |
| ------------------- | ------- | ------------------ |
| Sonar Deep Research | -       | 0.5 credits        |
| Sonar               | High    | 0.5 credits        |
| Sonar               | Medium  | 0.4 credits        |
| Sonar               | Low     | 0.3 credits        |
| Sonar Pro           | High    | 1.0 credit         |
| Sonar Pro           | Medium  | 0.8 credits        |
| Sonar Pro           | Low     | 0.6 credits        |

## Rate limits

* Sonar Deep Research: 5 requests per minute
* Other models: 1,000 requests per minute

Cargo automatically handles rate limiting to ensure reliable execution.

## Best practices

* Use Sonar Deep Research for comprehensive reports on complex topics
* Use Sonar or Sonar Pro for quick lookups and real-time information
* Enable domain filters to focus research on authoritative sources
* Use JSON schema output for structured data extraction
* Set appropriate search recency for time-sensitive queries


# Phantombuster
Source: https://docs.getcargo.ai/integration/phantombuster

Connect Phantombuster to launch agents and sync their results in your workflows.

## How to set up Phantombuster

### Authentication

Phantombuster uses API key authentication:

1. Sign up at [phantombuster.com](https://phantombuster.com)
2. Open your Workspace settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

<Note>
  **Code slugs** — integration slug: `phantombuster`. Action: `launchAgent`. In a [workflow](/workflows/overview), declare the connector in `uses` and call `uses.<key>.launchAgent(...)`.
</Note>

Cargo spreads requests at up to 100 calls per minute against the Phantombuster API.

## Phantombuster actions

### Launch Agent

Launch a Phantombuster agent, wait for the run to finish, and return its result items.

**Required fields:**

* **Agent**: Select the agent to launch

**Optional fields:**

* **Argument**: JSON argument to pass to the agent

**Use case:** Trigger a Phantombuster scraping or automation agent from a workflow and use its output downstream.

## Data models

Phantombuster also provides a **Fetch Agent Results** extractor, so you can sync agent output into Cargo as records without launching the agent yourself:

* Pick the agent to fetch results from
* Cargo fetches the result object of each finished agent run and turns items into records (columns are inferred from the items, deduplicated by a content hash)
* Creating the model backfills the agent's past runs — Cargo walks back through the agent's history, not just its most recent runs
* Syncs are then incremental — only runs that ended after the last sync are fetched, at most every 30 minutes

**Use case:** Keep a Cargo model up to date with the leads a scheduled Phantombuster agent produces.

## Best practices

* Validate the **Argument** field is valid JSON — the action fails otherwise
* Use the extractor (rather than the action) when the agent runs on its own schedule in Phantombuster
* Agent runs that error, crash, or time out fail the action with the agent's exit message


# Piloterr
Source: https://docs.getcargo.ai/integration/piloterr

Build company lists with Piloterr's B2B database

Piloterr is a B2B data platform that provides access to company information for lead generation and market research. The Cargo integration enables you to fetch company data based on filters.

## Authentication

Connect to Piloterr using your API key.

### Connection details

| Field       | Description           |
| ----------- | --------------------- |
| **API Key** | Your Piloterr API key |

***

## Data models

### Fetch companies

Build company lists by applying filters to Piloterr's database.

**Configuration**

| Field      | Description                     |
| ---------- | ------------------------------- |
| **Filter** | Define filter conditions        |
| **Sort**   | Sort results                    |
| **Limit**  | Maximum records (default: 1000) |

**Filterable fields**

| Field                 | Description            |
| --------------------- | ---------------------- |
| `industry`            | Company industry       |
| `staff_range`         | Employee count range   |
| `headquarter_country` | Company HQ country     |
| `domain`              | Company website domain |
| `website`             | Company website URL    |
| `linkedin_url`        | Company LinkedIn URL   |

<Tip>
  Combine multiple filters to build highly targeted company lists.
</Tip>

***

## Credits

| Action          | Cost                    |
| --------------- | ----------------------- |
| Fetch companies | 0.01 credits per record |

***

## Account unification

Piloterr data automatically unifies with your existing accounts using:

* **Domain** matching
* **Website URL** domain extraction
* **LinkedIn URL** handle extraction

***

## Use cases

<AccordionGroup>
  <Accordion title="List building" icon="list">
    Build targeted company lists based on industry, size, and location.
  </Accordion>

  <Accordion title="Market research" icon="chart-pie">
    Analyze company data for market sizing and segmentation.
  </Accordion>

  <Accordion title="Account enrichment" icon="database">
    Enrich existing account data with additional company information.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use specific filters** - Narrow your search criteria to get more relevant results
2. **Leverage autocomplete** - Industry and country fields offer autocomplete suggestions
3. **Sync regularly** - Schedule regular syncs to keep your company data fresh


# Pipedrive
Source: https://docs.getcargo.ai/integration/pipedrive

This page outlines how to use the Pipedrive integration to manage your sales CRM data in Cargo.

Pipedrive is a sales CRM designed to help small teams manage leads and deals with visual pipelines and smart automation. Cargo's native integration with Pipedrive allows you to manage organizations, persons, deals, and leads directly from your workflows.

## How to set up Pipedrive

To connect Pipedrive, you'll need your company domain and an API token.

### Connection details

| Field              | Description                      |
| ------------------ | -------------------------------- |
| **Company Domain** | Your Pipedrive company subdomain |
| **API Token**      | Your Pipedrive API token         |

<Tip>
  Find your API token in Pipedrive under **Settings → Personal preferences →
  API**.
</Tip>

Once the connector is created, you can:

* **Set up a Pipedrive data model** — Create data models from your Pipedrive objects to trigger Plays and power model search actions.
* **Use Pipedrive in workflows** — Choose **Pipedrive** from the node catalog within a **Play**, **Tool**, or **Agent**.

***

## Pipedrive actions

<Tip>
  All Pipedrive actions support Organizations, Persons, Deals, and Leads, giving
  you full control over your sales pipeline from Cargo.
</Tip>

### Get record

Retrieve a single record from Pipedrive by its ID.

**Use cases**

* **Data lookup** – Fetch record details for use in workflows
* **Conditional logic** – Retrieve data to make routing decisions
* **Enrichment context** – Get existing data before updating

**Configuration**

| Field           | Description                                |
| --------------- | ------------------------------------------ |
| **Object type** | Select Organization, Person, Deal, or Lead |
| **ID**          | The Pipedrive ID of the record to retrieve |

### Insert record

Create a new record in Pipedrive.

**Use cases**

* **Lead capture** – Create new leads from inbound sources
* **Organization creation** – Add new companies to your pipeline
* **Deal creation** – Create deals for new opportunities

**Configuration**

| Field           | Description                                |
| --------------- | ------------------------------------------ |
| **Object type** | Select Organization, Person, Deal, or Lead |
| **Mappings**    | Map Pipedrive fields to values             |

### Update records

Update existing records that match specified criteria.

**Use cases**

* **Data enrichment** – Update records with enriched information
* **Status updates** – Update deal stages or lead statuses
* **Field updates** – Bulk update specific fields

**Configuration**

| Field                    | Description                                  |
| ------------------------ | -------------------------------------------- |
| **Object type**          | Select Organization, Person, Deal, or Lead   |
| **Matching Value**       | The value to match against                   |
| **Field from Pipedrive** | The field to match on                        |
| **Mappings**             | Map Pipedrive fields to new values           |
| **Skip if exist**        | Update property only if it's currently empty |

<Info>
  Use the **Skip if exist** option to preserve existing data and only fill in
  missing fields.
</Info>

### Upsert records

Insert new records or update existing ones based on matching criteria.

**Use cases**

* **Data sync** – Sync records from external systems without duplicates
* **Idempotent operations** – Safely retry operations
* **Master data management** – Maintain a single source of truth

**Configuration**

| Field                    | Description                                  |
| ------------------------ | -------------------------------------------- |
| **Object type**          | Select Organization, Person, Deal, or Lead   |
| **Matching Value**       | The value to match against                   |
| **Field from Pipedrive** | The field to match on                        |
| **Mappings**             | Map Pipedrive fields to values               |
| **Skip if exist**        | Update property only if it's currently empty |

### Delete records

Delete records from Pipedrive that match specified criteria.

**Use cases**

* **Data cleanup** – Remove outdated or invalid records
* **GDPR compliance** – Delete personal data upon request
* **Pipeline hygiene** – Remove unqualified leads

**Configuration**

| Field                    | Description                                |
| ------------------------ | ------------------------------------------ |
| **Object type**          | Select Organization, Person, Deal, or Lead |
| **Matching Value**       | The value to match against                 |
| **Field from Pipedrive** | The field to match on                      |

<Warning>
  Deleting records is permanent and cannot be undone. Verify your matching
  criteria before executing this action.
</Warning>

### Search records

Retrieve multiple records from Pipedrive based on search criteria.

**Use cases**

* **Data retrieval** – Find records matching specific terms
* **Duplicate detection** – Search for existing records before creating new ones
* **Bulk operations** – Retrieve records for processing in group nodes

**Configuration**

| Field               | Description                                         |
| ------------------- | --------------------------------------------------- |
| **Object type**     | Select Organization, Person, Deal, or Lead          |
| **Term**            | The search term to match against                    |
| **Fields to match** | Specific fields to search (defaults to all)         |
| **Exact match**     | Enable for exact matching (not case sensitive)      |
| **Limit**           | Maximum records to retrieve (default: 10, max: 100) |

***

## Pipedrive data models

Cargo allows you to create data models on top of your Pipedrive data that can be used to trigger Plays and power workflows.

### Creating Pipedrive data models

Configure the following when creating a data model:

| Field           | Description                                |
| --------------- | ------------------------------------------ |
| **Object type** | Select Organization, Person, Deal, or Lead |

### Object types available

<AccordionGroup>
  <Accordion title="Organization models" icon="building">
    **Use cases** - Track company records with custom fields - Trigger workflows
    when organizations are created or updated - Build account-based workflows
  </Accordion>

  <Accordion title="Person models" icon="user">
    **Use cases** - Manage contact information and relationships - Trigger
    workflows on contact changes - Power contact enrichment workflows
  </Accordion>

  <Accordion title="Deal models" icon="handshake">
    **Use cases** - Track opportunities through your pipeline - Trigger
    workflows on deal stage changes - Monitor deal velocity and conversion
  </Accordion>

  <Accordion title="Lead models" icon="bullseye">
    **Use cases** - Manage early-stage prospects - Trigger qualification
    workflows - Track lead conversion rates
  </Accordion>
</AccordionGroup>


# PostgreSQL
Source: https://docs.getcargo.ai/integration/postgresql

This page outlines how to use the PostgreSQL integration to create and manage your database in Cargo.

PostgreSQL is a powerful, open-source relational database system with over 35 years of active development. Cargo's native integration with PostgreSQL allows you to connect your database, create data models, and execute SQL operations directly in your workflows.

<Tip>
  **Supabase compatible** — This integration works with [Supabase](https://supabase.com), Neon, Railway, and any PostgreSQL-compatible database.
</Tip>

## How to set up PostgreSQL

### Prerequisites

Before connecting PostgreSQL to Cargo, ensure you have:

* An active PostgreSQL server (version 9.6 or higher)
* Network connectivity between Cargo and your PostgreSQL server
* A database user with appropriate permissions
* SSL enabled for secure connections (recommended)

### Connection details

To set up the connection, provide the following details when creating the connector:

| Field        | Description                                   |
| ------------ | --------------------------------------------- |
| **Host**     | Your PostgreSQL server hostname or IP address |
| **Port**     | Default is `5432`                             |
| **Database** | Your database name                            |
| **Username** | The Cargo service user (e.g., `cargo_user`)   |
| **Password** | The user's password                           |
| **SSL**      | Enable SSL/TLS encryption (recommended)       |

<Tabs>
  <Tab title="Standard PostgreSQL">
    Use your PostgreSQL server's hostname and credentials directly.

    ```
    Host: db.example.com
    Port: 5432
    Database: myapp
    Username: cargo_user
    Password: ********
    SSL: true
    ```
  </Tab>

  <Tab title="Supabase">
    Find your connection details in **Project Settings → Database**.

    ```
    Host: db.xxxxxxxxxxxx.supabase.co
    Port: 5432
    Database: postgres
    Username: postgres
    Password: ********
    SSL: true
    ```

    <Tip>
      Use the **Direct connection** string for best performance with Cargo.
    </Tip>
  </Tab>

  <Tab title="Neon">
    Find your connection details in your Neon project dashboard.

    ```
    Host: ep-xxxxx.region.aws.neon.tech
    Port: 5432
    Database: neondb
    Username: your_username
    Password: ********
    SSL: true
    ```
  </Tab>
</Tabs>

***

## PostgreSQL actions

Once connected, you can use PostgreSQL in your workflows with the following actions:

### Insert

Insert new records into a PostgreSQL table.

**Configuration**

| Field        | Description                                       |
| ------------ | ------------------------------------------------- |
| **Schema**   | The PostgreSQL schema containing the target table |
| **Table**    | The table to insert data into                     |
| **Mappings** | Map columns to values using expressions           |

**Use cases**

* **Lead capture** – Insert new leads from form submissions or enrichment workflows
* **Event logging** – Record workflow events and outcomes
* **Data aggregation** – Store computed results for reporting

### Update

Update existing records in a PostgreSQL table based on a matching column.

**Configuration**

| Field               | Description                                       |
| ------------------- | ------------------------------------------------- |
| **Schema**          | The PostgreSQL schema containing the target table |
| **Table**           | The table to update                               |
| **Matching Column** | The column to match records against               |
| **Matching Value**  | The value to match (supports expressions)         |
| **Mappings**        | Map columns to new values using expressions       |

**Use cases**

* **Data enrichment** – Update records with enriched data from external sources
* **Status updates** – Mark records as processed or update stages
* **Sync external changes** – Keep PostgreSQL in sync with CRM or other systems

### Upsert

Create new records or update existing ones based on a matching column. Uses PostgreSQL's native `ON CONFLICT` clause for optimal performance.

**Configuration**

| Field               | Description                                       |
| ------------------- | ------------------------------------------------- |
| **Schema**          | The PostgreSQL schema containing the target table |
| **Table**           | The table to upsert into                          |
| **Matching Column** | The column to match records against               |
| **Matching Value**  | The value to match (supports expressions)         |
| **Mappings**        | Map columns to values using expressions           |

**Use cases**

* **Data sync** – Keep your database updated regardless of whether records exist
* **Idempotent operations** – Safely retry operations without creating duplicates
* **Master data management** – Maintain a single source of truth

<Info>
  The upsert action requires a unique constraint or primary key on the matching column.
</Info>

### Delete

Delete records from a PostgreSQL table based on a matching column.

**Configuration**

| Field               | Description                                       |
| ------------------- | ------------------------------------------------- |
| **Schema**          | The PostgreSQL schema containing the target table |
| **Table**           | The table to delete from                          |
| **Matching Column** | The column to match records against               |
| **Matching Value**  | The value to match (supports expressions)         |

**Use cases**

* **Data cleanup** – Remove outdated or invalid records
* **GDPR compliance** – Delete personal data on request
* **Workflow automation** – Remove processed records from staging tables

***

## PostgreSQL data models

Cargo allows you to create data models on top of your PostgreSQL data that can be used to trigger Plays and power workflows.

### Creating PostgreSQL data models

To create a PostgreSQL data model:

1. Navigate to **Data Models** in Cargo
2. Click **Create data model**
3. Select **PostgreSQL** as the source
4. Configure the following fields:

| Field             | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| **Name**          | Choose a descriptive name for your model                    |
| **Slug**          | Set a unique identifier that cannot be changed once created |
| **Schema**        | Select the PostgreSQL schema containing your data           |
| **Table**         | Select the table or view to model                           |
| **ID Column**     | The column containing unique record identifiers             |
| **Title Column**  | The column to display as the record title                   |
| **Cursor Column** | (Optional) Column for incremental syncing (date or number)  |

### Using PostgreSQL data models

Once created, your PostgreSQL data model can be used to:

* **Trigger Plays** – Start automated workflows when data changes
* **Power enrichment** – Use PostgreSQL data to enrich records in workflows
* **Create segments** – Filter and target specific records from your data

***

## Database user setup

For best security practices, create a dedicated user with only the necessary permissions:

```sql theme={null}
-- Create a dedicated user
CREATE USER cargo_user WITH PASSWORD 'your_secure_password';

-- Grant connect privilege
GRANT CONNECT ON DATABASE your_database TO cargo_user;

-- Grant usage on schema
GRANT USAGE ON SCHEMA public TO cargo_user;

-- Grant permissions on specific tables
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE your_table TO cargo_user;

-- Or grant on all tables in a schema
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO cargo_user;

-- For future tables created in the schema
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO cargo_user;
```

***

## Network configuration

If you restrict access to your PostgreSQL server, add these Cargo IP addresses to your firewall or security group:

* `3.251.34.134`
* `54.220.135.99`
* `79.125.105.52`

<Tabs>
  <Tab title="Supabase">
    In Supabase, network restrictions are configured in **Project Settings → Database → Network restrictions**.
  </Tab>

  <Tab title="AWS RDS">
    Update your RDS security group to allow inbound traffic on port 5432 from Cargo's IPs.
  </Tab>

  <Tab title="Standard PostgreSQL">
    Update your `pg_hba.conf` to allow connections from Cargo's IP addresses.
  </Tab>
</Tabs>

***

## Security

* All PostgreSQL connections can be encrypted using SSL/TLS
* Credentials are securely stored and encrypted at rest
* Cargo uses dedicated user credentials with minimal required permissions
* We recommend enabling SSL and using strong passwords


# PredictLeads
Source: https://docs.getcargo.ai/integration/predict-leads

Connect PredictLeads to access company intelligence, job openings, and technology data in your workflows.

## How to set up PredictLeads

### Authentication

PredictLeads uses dual-key authentication:

1. Sign up at [predictleads.com](https://predictleads.com)
2. Navigate to your API settings
3. Obtain both credentials:
   * **API Key**
   * **API Token**
4. Enter both in Cargo when connecting

## PredictLeads actions

### Enrich company

Get comprehensive information about a company.

**Required fields:**

* **Domain**: Company domain to research

**Returns:** Company overview, industry, size, funding, and more.

### Search products

Find products associated with a company.

**Required fields:**

* **Domain**: Company domain

**Optional fields:**

* **Limit**: Maximum number of results

**Use case:** Understand what products a company offers or uses.

### Search job openings

Find current job postings at a company.

**Required fields:**

* **Domain**: Company domain

**Optional fields:**

* **Limit**: Maximum number of results

**Use cases:**

* Identify hiring signals for sales triggers
* Understand company growth areas
* Find potential contacts by role

### Search technologies

Discover technologies used by a company.

**Required fields:**

* **Domain**: Company domain

**Optional fields:**

* **Limit**: Maximum number of results

**Use case:** Technology-based prospecting and competitive analysis.

### Search website evolutions

Track changes to a company's website over time.

**Required fields:**

* **Domain**: Company domain

**Optional fields:**

* **Limit**: Maximum number of results

**Use case:** Monitor company messaging and positioning changes.

### Search connections

Find business connections and relationships.

**Required fields:**

* **Domain**: Company domain

**Optional fields:**

* **Limit**: Maximum number of results

**Use case:** Map company ecosystems and partnerships.

### Search events

Find company events and announcements.

**Required fields:**

* **Domain**: Company domain

**Optional fields:**

* **Limit**: Maximum number of results

**Use case:** Trigger outreach based on company events.

### Search GitHub repositories

Find company's open source projects.

**Required fields:**

* **Domain**: Company domain

**Optional fields:**

* **Limit**: Maximum number of results

**Use case:** Developer-focused prospecting and technology assessment.

## Response data examples

### Job opening data:

| Field      | Description     |
| ---------- | --------------- |
| title      | Job title       |
| department | Department      |
| location   | Job location    |
| posted\_at | When posted     |
| url        | Application URL |

### Technology data:

| Field       | Description         |
| ----------- | ------------------- |
| name        | Technology name     |
| category    | Technology category |
| first\_seen | When first detected |
| last\_seen  | When last detected  |

## Best practices

* Use job openings as buying signals
* Combine technology data with your ICP criteria
* Monitor events for timely outreach triggers
* Cache results for frequently researched companies
* Use multiple search types for comprehensive intelligence


# PromptLayer
Source: https://docs.getcargo.ai/integration/prompt-layer

Run PromptLayer workflows for LLM-powered automation

PromptLayer is a platform for managing and running LLM workflows. The Cargo integration enables you to trigger PromptLayer workflows with dynamic input variables.

## Authentication

Connect to PromptLayer using your API key.

### Connection details

| Field       | Description              |
| ----------- | ------------------------ |
| **API key** | Your PromptLayer API key |

***

## PromptLayer actions

### Run

Execute a PromptLayer workflow with custom input variables.

**Configuration**

| Field                | Description                         |
| -------------------- | ----------------------------------- |
| **Workflow**         | Select a workflow from your account |
| **Workflow version** | Specific version to run (optional)  |
| **Input variables**  | Key-value pairs for workflow inputs |

**Input variables**

Add dynamic input variables to pass data into your workflow:

| Field     | Description                    |
| --------- | ------------------------------ |
| **Name**  | Variable name (as in workflow) |
| **Value** | Value to pass (expression)     |

***

## Use cases

<AccordionGroup>
  <Accordion title="Content generation" icon="file-lines">
    Generate personalized content using LLM workflows.
  </Accordion>

  <Accordion title="Data extraction" icon="database">
    Extract structured data from unstructured text.
  </Accordion>

  <Accordion title="Classification" icon="tags">
    Classify leads, tickets, or content using AI.
  </Accordion>

  <Accordion title="Summarization" icon="compress">
    Summarize long-form content for quick consumption.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Define workflows in PromptLayer** - Create and test workflows in PromptLayer first
2. **Map input variables** - Ensure variable names match between Cargo and PromptLayer
3. **Version control** - Use specific versions for production stability


# Prospeo
Source: https://docs.getcargo.ai/integration/prospeo

Connect Prospeo to find emails, verify contacts, and enrich LinkedIn profiles in your workflows.

## How to set up Prospeo

### Authentication

Prospeo uses API key authentication:

1. Sign up at [prospeo.io](https://prospeo.io)
2. Navigate to your API settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## Prospeo actions

### Find email

Find a person's email address using their name and company domain.

**Required fields:**

* **Company domain**: The company's website domain

**Optional fields:**

* **First name**: Person's first name
* **Last name**: Person's last name
* **Full name**: Full name (alternative to first/last)

**Credits:** 0.5 credits per request

**Use case:** Find professional emails for prospects when you have their name and company.

### Verify email

Check if an email address is valid and deliverable.

**Required fields:**

* **Email**: The email address to verify

**Optional fields:**

* **Email anon ID**: Anonymous identifier for tracking

**Credits:** 0.1 credits per request

**Use case:** Clean your email lists and ensure high deliverability before campaigns.

### Enrich LinkedIn

Get detailed profile information from a LinkedIn URL.

**Required fields:**

* **URL**: The person's LinkedIn profile URL

**Optional fields:**

* **Profile only**: Only return data from LinkedIn profile (no email lookup)

**Credits:** 0.5 credits per request

**Use cases:**

* Enrich leads captured from LinkedIn
* Get comprehensive profile data including email
* Build complete prospect profiles

### Find phone

Find a person's phone number using their LinkedIn URL.

**Required fields:**

* **URL**: The person's LinkedIn profile URL

**Credits:** 3 credits per request

**Use case:** Get direct phone numbers for high-priority prospects.

### Search emails

Find multiple email addresses at a company domain.

**Required fields:**

* **Domain**: Company domain to search

**Optional fields:**

* **Email type**: Filter by All, Generic, or Professional emails
* **Limit**: Maximum number of results
* **Company enrichment**: Include company details in response

**Credits:** 1 credit per request

**Use case:** Build contact lists for account-based outreach campaigns.

## Response data

### Find email returns:

| Field         | Description         |
| ------------- | ------------------- |
| email         | Found email address |
| email\_status | Verification status |
| first\_name   | First name          |
| last\_name    | Last name           |
| domain        | Company domain      |

### Enrich LinkedIn returns:

| Field         | Description         |
| ------------- | ------------------- |
| email         | Email address       |
| first\_name   | First name          |
| last\_name    | Last name           |
| headline      | LinkedIn headline   |
| company       | Current company     |
| position      | Job title           |
| location      | Geographic location |
| linkedin\_url | Profile URL         |

## Credits summary

| Action          | Credits |
| --------------- | ------- |
| Verify email    | 0.1     |
| Find email      | 0.5     |
| Enrich LinkedIn | 0.5     |
| Search emails   | 1       |
| Find phone      | 3       |

## Rate limits

Prospeo API has a rate limit of 150 requests per minute. Cargo handles rate limiting automatically with caching support to optimize credit usage.


# ProxyCurl
Source: https://docs.getcargo.ai/integration/proxycurl

Enrich and search LinkedIn data with ProxyCurl

ProxyCurl is a LinkedIn data API that enables you to enrich profiles and search for people, companies, and jobs. The Cargo integration provides access to ProxyCurl's enrichment and search capabilities.

## Authentication

Connect to ProxyCurl using your API key.

### Connection details

| Field       | Description            |
| ----------- | ---------------------- |
| **API Key** | Your ProxyCurl API key |

***

## ProxyCurl actions

### Enrich

Retrieve detailed information about a person, company, role, or job.

**Object types**

| Type        | Description                          |
| ----------- | ------------------------------------ |
| **Role**    | Enrich by role and company name      |
| **Person**  | Enrich by name, company, title, etc. |
| **Company** | Enrich by domain, name, or location  |
| **Job**     | Enrich by LinkedIn job URL           |

**Person filters**

| Filter         | Description           |
| -------------- | --------------------- |
| Company domain | Domain of the company |
| First name     | Person's first name   |
| Last name      | Person's last name    |
| Location       | Person's location     |
| Title          | Job title             |

**Company filters**

| Filter           | Description             |
| ---------------- | ----------------------- |
| Company domain   | Domain of the company   |
| Company name     | Name of the company     |
| Company location | Location of the company |

### Search

Search for people, companies, or jobs matching specific criteria.

**Object types**

| Type        | Description             |
| ----------- | ----------------------- |
| **Person**  | Search for people       |
| **Company** | Search for companies    |
| **Job**     | Search for job postings |

***

## Credits

| Action | Cost                    |
| ------ | ----------------------- |
| Enrich | 1 credit per enrichment |
| Search | 1 credit per result     |

***

## Use cases

<AccordionGroup>
  <Accordion title="Lead enrichment" icon="user-plus">
    Enrich leads with LinkedIn profile data including experience and education.
  </Accordion>

  <Accordion title="Company research" icon="building">
    Get comprehensive company profiles from LinkedIn.
  </Accordion>

  <Accordion title="Role-based search" icon="briefcase">
    Find people by their current role and company.
  </Accordion>

  <Accordion title="Job monitoring" icon="magnifying-glass">
    Track job postings for hiring signals.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use multiple identifiers** - Provide domain + name for better match rates
2. **Rate limits** - ProxyCurl allows 300 requests per minute
3. **Cache results** - Results are cached to reduce credit usage on repeated lookups


# RB2B
Source: https://docs.getcargo.ai/integration/rb2b

Identify website visitors with RB2B person-level identification

RB2B is a website visitor identification platform that reveals individual professionals visiting your website. The Cargo integration enables you to receive real-time visitor data.

## Authentication

RB2B connects through webhook integration. No additional configuration is required.

***

## Data models

### Listen profiles

Receive real-time notifications when professionals visit your website.

**Configuration**

No additional configuration required. RB2B will push profile data to Cargo automatically.

**Data returned**

Each profile includes:

* Professional information (name, title, company)
* Contact details when available
* Visit activity data

***

## Use cases

<AccordionGroup>
  <Accordion title="Person-level identification" icon="user">
    Identify individual visitors beyond company-level data.
  </Accordion>

  <Accordion title="Sales alerts" icon="bell">
    Get notified when specific personas visit your website.
  </Accordion>

  <Accordion title="Personalized outreach" icon="envelope">
    Trigger personalized follow-up based on visitor profiles.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Prioritize high-intent pages** - Focus on visitors to pricing, demo, or product pages
2. **Match to existing leads** - Connect visitor data with your CRM records
3. **Respect privacy** - Use visitor data responsibly and in compliance with regulations


# Redshift
Source: https://docs.getcargo.ai/integration/redshift

This page outlines how to use the Redshift integration to create and manage your data warehouse in Cargo.

Amazon Redshift is a fast, fully managed cloud data warehouse that makes it simple and cost-effective to analyze data using standard SQL. Cargo's native integration with Redshift allows you to use it as your system of record—powering data models, plays, and automated workflows.

## How to set up Redshift

### Prerequisites

Before connecting Redshift to Cargo, ensure you have:

* An active Amazon Redshift cluster
* Network connectivity between Cargo and your Redshift cluster
* A dedicated schema and user for Cargo
* Proper IAM permissions and database credentials

### Connection details

To set up the connection, provide the following details when creating the connector:

| Field        | Description                                                               |
| ------------ | ------------------------------------------------------------------------- |
| **Host**     | Your Redshift endpoint (e.g., `cluster-id.region.redshift.amazonaws.com`) |
| **Port**     | Default is `5439`                                                         |
| **Database** | Your database name                                                        |
| **Username** | The Cargo service user (e.g., `cargo_user`)                               |
| **Password** | The user's password                                                       |

<Tip>
  Find your Redshift endpoint in the AWS Console under **Redshift → Clusters →
  Your Cluster → General information**.
</Tip>

***

## Redshift actions

Once connected, you can use Redshift in your workflows with the following actions:

### Insert

Insert new records into a Redshift table.

**Configuration**

| Field        | Description                                     |
| ------------ | ----------------------------------------------- |
| **Schema**   | The Redshift schema containing the target table |
| **Table**    | The table to insert data into                   |
| **Mappings** | Map columns to values using expressions         |

**Use cases**

* **Lead capture** – Insert new leads from form submissions or enrichment workflows
* **Event logging** – Record workflow events and outcomes
* **Data aggregation** – Store computed results for reporting

### Update

Update existing records in a Redshift table based on a matching column.

**Configuration**

| Field               | Description                                     |
| ------------------- | ----------------------------------------------- |
| **Schema**          | The Redshift schema containing the target table |
| **Table**           | The table to update                             |
| **Matching Column** | The column to match records against             |
| **Matching Value**  | The value to match (supports expressions)       |
| **Mappings**        | Map columns to new values using expressions     |

**Use cases**

* **Data enrichment** – Update records with enriched data from external sources
* **Status updates** – Mark records as processed or update stages
* **Sync external changes** – Keep Redshift in sync with CRM or other systems

### Upsert

Create new records or update existing ones based on a matching column.

**Configuration**

| Field               | Description                                     |
| ------------------- | ----------------------------------------------- |
| **Schema**          | The Redshift schema containing the target table |
| **Table**           | The table to upsert into                        |
| **Matching Column** | The column to match records against             |
| **Matching Value**  | The value to match (supports expressions)       |
| **Mappings**        | Map columns to values using expressions         |

**Use cases**

* **Data sync** – Keep your warehouse updated regardless of whether records exist
* **Idempotent operations** – Safely retry operations without creating duplicates
* **Master data management** – Maintain a single source of truth

### Delete

Delete records from a Redshift table based on a matching column.

**Configuration**

| Field               | Description                                     |
| ------------------- | ----------------------------------------------- |
| **Schema**          | The Redshift schema containing the target table |
| **Table**           | The table to delete from                        |
| **Matching Column** | The column to match records against             |
| **Matching Value**  | The value to match (supports expressions)       |

**Use cases**

* **Data cleanup** – Remove outdated or invalid records
* **GDPR compliance** – Delete personal data on request
* **Workflow automation** – Remove processed records from staging tables

***

## Redshift data models

Cargo allows you to create data models on top of your Redshift data that can be used to trigger Plays and power workflows.

### Creating Redshift data models

To create a Redshift data model:

1. Navigate to **Data Models** in Cargo
2. Click **Create data model**
3. Select **Redshift** as the source
4. Configure the following fields:

| Field             | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| **Name**          | Choose a descriptive name for your model                    |
| **Slug**          | Set a unique identifier that cannot be changed once created |
| **Schema**        | Select the Redshift schema containing your data             |
| **Table**         | Select the table or view to model                           |
| **ID Column**     | The column containing unique record identifiers             |
| **Title Column**  | The column to display as the record title                   |
| **Cursor Column** | (Optional) Column for incremental syncing (date or number)  |

### Using Redshift data models

Once created, your Redshift data model can be used to:

* **Trigger Plays** – Start automated workflows when data changes
* **Power enrichment** – Use Redshift data to enrich records in workflows
* **Create segments** – Filter and target specific records from your data

***

## Network configuration

If you restrict access to your Redshift cluster, add these Cargo IP addresses to your security group or VPC whitelist:

* `3.251.34.134`
* `54.220.135.99`
* `79.125.105.52`

**Update via AWS CLI**

```bash theme={null}
aws ec2 authorize-security-group-ingress \
    --group-id sg-your-security-group-id \
    --protocol tcp \
    --port 5439 \
    --cidr 3.251.34.134/32
```

***

## Security

* All Redshift connections are encrypted using SSL/TLS
* Credentials are securely stored and encrypted at rest
* Cargo uses dedicated user credentials with minimal required permissions
* Cargo never overwrites existing tables—it always creates its own


# Replicas
Source: https://docs.getcargo.ai/integration/replicas

Launch background coding agents in cloud workspaces

Replicas runs coding agents in cloud workspaces built from an environment — a config bundle that carries the repository binding plus the variables, files, skills and MCPs the agent gets. The Cargo integration lets a workflow launch an agent and use whatever it produced (branches, pull requests) in downstream nodes.

## Authentication

Connect to Replicas using an API key created from the Replicas dashboard under **Organization → Settings → API Keys**.

### Connection details

| Field       | Description           |
| ----------- | --------------------- |
| **API Key** | Your Replicas API key |

***

## Replicas actions

### Launch agent

Create a workspace and send an initial message to a coding agent.

**Configuration**

| Field              | Description                                                                       |
| ------------------ | --------------------------------------------------------------------------------- |
| **Environment**    | The Replicas environment the workspace is created from                            |
| **Prompt**         | The initial message sent to the coding agent                                      |
| **Workspace name** | Name of the workspace — whitespace is replaced with dashes                        |
| **Coding agent**   | Claude Code, Codex, Cursor, Opencode or Pi                                        |
| **Model**          | Model identifier for the selected coding agent                                    |
| **Thinking level** | How much reasoning effort the agent puts in                                       |
| **Plan mode**      | Have the agent propose a plan instead of editing code                             |
| **Compute size**   | Small (2 vCPU, 8 GB) or Large (4 vCPU, 16 GB)                                     |
| **Lifecycle**      | Whether the workspace keeps running, sleeps or is archived once the agent is done |

The **Environment** dropdown lists the team and personal environments in your Replicas
organization. The Global environment is not listed: it only layers configuration onto the
other environments and has no repository binding, so it cannot back a workspace.

Leave **Workspace name** empty to get a name derived from the workflow node and the record
being processed.

**Waiting for the agent**

The node stays pending until Replicas calls back, so downstream nodes run against a
finished agent rather than a workspace that has only just started. Replicas notifies Cargo
directly — nothing is polled — and the node resumes on the `replica.turn_completed`
callback. A `replica.error` callback fails the node with the reason Replicas reported.

**Output**

| Field             | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| `id`              | Workspace identifier                                        |
| `name`            | Workspace name                                              |
| `status`          | Workspace status when the turn finished                     |
| `url`             | Link to the workspace in the Replicas dashboard             |
| `branches`        | Branch, default branch and pull request URLs per repository |
| `pullRequestUrls` | Every pull request URL the agent opened during the turn     |

***

## Use cases

<AccordionGroup>
  <Accordion title="Automated code changes" icon="code-branch">
    Turn a qualified request into a branch and a pull request without a human in the loop.
  </Accordion>

  <Accordion title="Codebase research" icon="magnifying-glass">
    Ask an agent to investigate a repository and feed its findings into the rest of the workflow.
  </Accordion>

  <Accordion title="Triage at scale" icon="list-check">
    Launch one agent per incoming issue and collect the pull requests they open.
  </Accordion>

  <Accordion title="Scheduled maintenance" icon="clock">
    Run dependency bumps or migrations on a schedule and review the resulting pull requests.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Give the agent a complete prompt** - It cannot ask follow-up questions mid-run
2. **Pick the environment carefully** - It decides which repository the agent works on
3. **Use plan mode to review first** - Have the agent propose an approach before it writes code
4. **Sleep or archive when done** - Workspaces bill per minute while they stay up


# Resend
Source: https://docs.getcargo.ai/integration/resend

Connect Resend to send transactional emails from Cargo workflows.

Resend is an email API for transactional email delivery. Cargo's native Resend integration lets you send template-based or raw HTML/text emails directly from your Tools, Plays, and Agents.

## How to set up Resend

To connect Resend, you need an API key from your Resend account.

### Connection details

| Field       | Description         |
| ----------- | ------------------- |
| **API Key** | Your Resend API key |

<Tip>Create an API key in Resend under **API Keys** and paste it into Cargo when creating the connector.</Tip>

Once the connector is created, you can:

* **Use Resend in workflows** — Choose **Resend** from the node catalog in a **Play**, **Tool**, or **Agent**.

***

## Resend actions

### Send email

Send an email with Resend using either:

* a **published template** with variables, or
* **raw HTML/text** content.

**Configuration**

| Field                  | Description                                                 |
| ---------------------- | ----------------------------------------------------------- |
| **From email**         | Sender email address                                        |
| **From name**          | Optional sender display name                                |
| **To email**           | Recipient email address                                     |
| **Subject**            | Required for HTML/text mode, optional when using a template |
| **Template**           | Optional template ID or alias                               |
| **Template variables** | Optional key-value mappings used with templates             |
| **HTML**               | Optional HTML body (must not be set with Template)          |
| **Text**               | Optional text body (must not be set with Template)          |
| **Reply to**           | Optional reply-to email address                             |

<Info>
  If **Template** is provided, do not send **HTML** or **Text** in the same action.
  Resend rejects that payload combination.
</Info>

***

## Template variables

When using templates, pass variables as key-value pairs in **Template variables**.

### Example

| Key            | Value                        |
| -------------- | ---------------------------- |
| `first_name`   | `{{contact.firstName}}`      |
| `company_name` | `{{account.name}}`           |
| `cta_url`      | `{{tool.output.meetingUrl}}` |

<Warning>
  Template variable keys must match the variables expected by your published
  Resend template.
</Warning>


# Reverse Contact
Source: https://docs.getcargo.ai/integration/reverse-contact

Connect Reverse Contact to enrich profiles and companies from email or LinkedIn in your workflows.

## How to set up Reverse Contact

### Authentication

Reverse Contact uses API key authentication. Cargo uses Reverse Contact's V2 API, so you need a V2 key (it starts with `rc_`):

1. Sign up at [reversecontact.com](https://reversecontact.com)
2. Open the [API Keys](https://app.reversecontact.com) page in your dashboard and create a V2 API key
3. Copy the key (prefix `rc_`)
4. Paste the API key in Cargo when connecting

Legacy `sk_` keys only worked with the retired V1 endpoints and will not authenticate.

## Reverse Contact actions

### Enrich profile from LinkedIn

Get comprehensive profile data from a LinkedIn URL.

**Required fields:**

* **LinkedIn URL**: Person's LinkedIn profile URL

**Returns:**

* Full name and contact details
* Current and past positions
* Education history
* Skills and certifications
* Social profiles

**Use case:** Convert LinkedIn profiles to enriched contact records.

### Enrich profile from email

Get profile information using an email address.

**Required fields:**

* **Email**: Person's email address

**Optional fields (improve matching):**

* **First name**: Person's first name
* **Last name**: Person's last name
* **Company name**: Current company name
* **Company domain**: Company domain

**Returns:**

* LinkedIn profile data
* Full profile information
* Company context

**Use case:** Reverse lookup email addresses to find LinkedIn profiles.

### Enrich company from LinkedIn

Get company information from LinkedIn company page.

**Required fields:**

* **LinkedIn URL**: Company's LinkedIn page URL

**Credits:** 1 credit per request

**Returns:**

* Company overview
* Industry and size
* Employee count
* Locations
* Description

**Use case:** Enrich accounts from LinkedIn company pages.

### Enrich company from domain

Get company information from a website domain.

**Required fields:**

* **Domain**: Company's website domain

**Returns:**

* Company profile
* Industry classification
* Size and location
* Social profiles

**Use case:** Enrich account data from domains.

## Response data

### Profile enrichment returns:

| Field         | Description             |
| ------------- | ----------------------- |
| full\_name    | Complete name           |
| headline      | LinkedIn headline       |
| title         | Current job title       |
| company       | Current employer        |
| location      | Geographic location     |
| industry      | Industry classification |
| experience    | Work history            |
| education     | Education history       |
| skills        | Listed skills           |
| linkedin\_url | LinkedIn profile URL    |

### Company enrichment returns:

| Field         | Description             |
| ------------- | ----------------------- |
| name          | Company name            |
| domain        | Website domain          |
| industry      | Industry classification |
| size          | Employee count          |
| founded       | Founding year           |
| description   | Company description     |
| locations     | Office locations        |
| linkedin\_url | LinkedIn company page   |

## Best practices

* Provide additional context (name, company) for email enrichment
* Use LinkedIn URL when available for most accurate results
* Combine profile and company enrichment for complete data
* Cache results to avoid redundant lookups
* Use for reverse email lookups to find LinkedIn profiles


# Rift
Source: https://docs.getcargo.ai/integration/rift

Manage contacts and campaigns with Rift

Rift is a sales engagement platform for managing outreach campaigns. The Cargo integration enables you to create and update contacts, and enroll them into campaigns.

## Authentication

Connect to Rift using your API key.

### Connection details

| Field       | Description       |
| ----------- | ----------------- |
| **API Key** | Your Rift API key |

***

## Rift actions

### Upsert contact

Create a new contact or update an existing one based on email address. Optionally enroll the contact into a campaign.

**Configuration**

| Field               | Description                      |
| ------------------- | -------------------------------- |
| **Email**           | Contact's email (required)       |
| **First name**      | Contact's first name             |
| **Last name**       | Contact's last name              |
| **Company**         | Company name                     |
| **Phone**           | Phone number                     |
| **Title**           | Job title                        |
| **LinkedIn**        | LinkedIn profile URL             |
| **Custom mappings** | Additional custom field mappings |

**Campaign enrollment (optional)**

| Field                    | Description                                 |
| ------------------------ | ------------------------------------------- |
| **Campaign**             | Campaign to enroll the contact into         |
| **Unenroll**             | Unenroll from other campaigns first         |
| **Launch**               | Launch the campaign if not running          |
| **Variables validation** | Validate all campaign variables are present |

***

## Use cases

<AccordionGroup>
  <Accordion title="Lead routing" icon="route">
    Route qualified leads directly into outreach campaigns.
  </Accordion>

  <Accordion title="Contact sync" icon="sync">
    Sync contact data from other systems to Rift.
  </Accordion>

  <Accordion title="Campaign enrollment" icon="play">
    Automatically enroll contacts in campaigns based on triggers.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use unenroll wisely** - Only unenroll when you want to force campaign reassignment
2. **Validate variables** - Enable variable validation to catch missing personalization data
3. **Map custom fields** - Use custom mappings for additional contact properties


# RocketReach
Source: https://docs.getcargo.ai/integration/rocketreach

Connect RocketReach to find contact information and enrich person profiles in your workflows.

## How to set up RocketReach

### Authentication

RocketReach uses API key authentication:

1. Log in to your RocketReach account
2. Navigate to **API** settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## RocketReach actions

### Lookup person

Find contact information and company details for a person.

**Input fields (provide as many as available):**

* **Name**: Full name of the person
* **Current employer**: Current company name
* **Title**: Job title
* **LinkedIn URL**: Person's LinkedIn profile URL
* **Email**: Known email address
* **NPI Number**: US healthcare professional identifier

**Lookup types:**

| Type                     | Description                       |
| ------------------------ | --------------------------------- |
| Standard                 | Default lookup                    |
| Premium                  | Enhanced data with more sources   |
| Premium (feeds disabled) | Premium without third-party feeds |
| Bulk                     | Optimized for high-volume lookups |
| Phone                    | Focus on phone number discovery   |
| Enrich                   | Enrich existing contact data      |

**Credits:** 1 credit per lookup

## Response data

RocketReach returns comprehensive contact information:

| Field             | Description              |
| ----------------- | ------------------------ |
| name              | Full name                |
| first\_name       | First name               |
| last\_name        | Last name                |
| title             | Job title                |
| current\_employer | Company name             |
| emails            | Array of email addresses |
| phones            | Array of phone numbers   |
| linkedin\_url     | LinkedIn profile URL     |
| city              | City                     |
| region            | State/Region             |
| country           | Country                  |

## Credits

RocketReach uses a credit-based system:

* Each lookup costs 1 credit
* Credits are tracked by Cargo

Caching is supported to avoid duplicate lookups for the same contact.

## Rate limits

RocketReach API has a rate limit of 250 requests per minute. Cargo handles rate limiting automatically.

## Best practices

* Provide LinkedIn URL for the most accurate matching
* Include company name with person name for better results
* Use caching to optimize credit usage
* Choose the appropriate lookup type for your use case
* Combine with email verification for highest quality data


# RSS Feed
Source: https://docs.getcargo.ai/integration/rss-feed

Connect to any RSS or Atom feed to ingest news, blogs, and updates into your workflows.

## How to set up RSS Feed

### Authentication

Most RSS feeds are public and don't require authentication. However, if you need to access protected feeds:

1. Add the RSS Feed integration in Cargo
2. Configure optional headers if authentication is required:
   * **Public headers**: Visible values
   * **Secret headers**: Encrypted values (API keys, tokens)

## RSS Feed data models

### Fetch RSS Feed

Pull items from any RSS 2.0, RSS 1.0, or Atom feed.

**Required fields:**

* **Feed URL**: The URL of the RSS or Atom feed

**Features:**

* Supports standard RSS 2.0, RSS 1.0, and Atom formats
* Minimum 30-minute sync interval
* Automatically parses feed structure

**Example feed URLs:**

```
https://techcrunch.com/feed/
https://feeds.bbci.co.uk/news/rss.xml
https://www.lesechos.fr/rss/finance.xml
```

## Feed item data

RSS feed items typically include:

| Field       | Description                 |
| ----------- | --------------------------- |
| title       | Item title                  |
| link        | URL to full article         |
| description | Summary or excerpt          |
| pubDate     | Publication date            |
| author      | Author name                 |
| category    | Content categories          |
| guid        | Unique identifier           |
| content     | Full content (if available) |

## Protected feeds

For feeds requiring authentication, configure headers:

**API Key authentication:**

```
Key: Authorization
Value: Bearer your-api-key
Type: Secret
```

**Basic authentication:**

```
Key: Authorization
Value: Basic base64(username:password)
Type: Secret
```

## Best practices

* Use reliable, stable feed URLs
* Set appropriate sync intervals based on feed update frequency
* Filter items by date to process only new content
* Combine with entity extraction for company/topic matching
* Store feed GUIDs to avoid reprocessing
* Handle feed errors gracefully (feeds can be unreliable)

## Use cases

* **Sales triggers**: Company announcements, funding news
* **Competitive intel**: Competitor blog and press monitoring
* **Industry research**: Track trends and developments
* **Content curation**: Aggregate relevant content
* **Account monitoring**: Follow target account news

## Supported formats

| Format  | Description                  |
| ------- | ---------------------------- |
| RSS 2.0 | Most common RSS format       |
| RSS 1.0 | Older RDF-based RSS format   |
| Atom    | Modern XML-based feed format |


# SalesIntel
Source: https://docs.getcargo.ai/integration/sales-intel

Access B2B company data with SalesIntel

SalesIntel is a B2B data platform that provides human-verified company and contact information. The Cargo integration enables you to enrich company data.

## Authentication

Connect to SalesIntel using your API key.

### Connection details

| Field       | Description             |
| ----------- | ----------------------- |
| **API Key** | Your SalesIntel API key |

***

## SalesIntel capabilities

### Company enrichment

Enrich company records with firmographic data including:

* Company details (name, location, industry)
* Employee count and revenue
* Technology stack
* Funding information
* Keywords and classifications

**Available filter fields**

| Field         | Description             |
| ------------- | ----------------------- |
| City          | Company city            |
| State         | Company state           |
| Country       | Company country         |
| Industry      | Industry classification |
| Technologies  | Technologies used       |
| Funding round | Last funding round type |
| Keywords      | Business keywords       |

***

## Use cases

<AccordionGroup>
  <Accordion title="Account enrichment" icon="building">
    Enrich CRM accounts with verified company data.
  </Accordion>

  <Accordion title="Technology targeting" icon="microchip">
    Identify companies using specific technologies.
  </Accordion>

  <Accordion title="Market segmentation" icon="chart-pie">
    Segment accounts by industry, size, and location.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use multiple filters** - Combine filters for more targeted results
2. **Leverage technology data** - Great for competitive displacement campaigns
3. **Cache results** - Results are cached to reduce API calls


# Sales Navigator
Source: https://docs.getcargo.ai/integration/sales-navigator

Access LinkedIn Sales Navigator data for prospecting

LinkedIn Sales Navigator is LinkedIn's premium sales tool for finding and engaging with prospects. The Cargo integration enables you to search leads and accounts, extract data, and access company insights.

## Authentication

Sales Navigator requires a connected LinkedIn Sales Navigator account through Cargo's LinkedIn integration.

***

## Sales Navigator actions

### Search leads

Search for leads based on specific criteria.

**Configuration**

Define search filters to find leads matching your ideal customer profile, including job title, seniority, company size, and location.

### Find company insights

Get detailed insights about a specific company.

**Configuration**

Provide company identifiers to retrieve insights including growth signals, hiring trends, and company updates.

### Find company metrics

Retrieve metrics and analytics for a company.

**Configuration**

Access company metrics including employee count trends and department breakdowns.

### Find employees count

Get the total employee count for a company.

**Configuration**

Provide company identifiers to retrieve current employee count data.

### Find employees distribution

Get the distribution of employees across functions and seniority levels.

**Configuration**

Analyze a company's organizational structure by department and level.

### Extract account search

Extract accounts from a saved Sales Navigator search.

**Configuration**

Provide a saved account search to extract matching companies.

### Extract lead search

Extract leads from a saved Sales Navigator search.

**Configuration**

Provide a saved lead search to extract matching contacts.

***

## Data models

### Fetch accounts

Sync accounts from Sales Navigator searches.

**Configuration**

Configure which saved account searches to sync and how frequently.

### Fetch leads

Sync leads from Sales Navigator searches.

**Configuration**

Configure which saved lead searches to sync and how frequently.

***

## Use cases

<AccordionGroup>
  <Accordion title="Account research" icon="building">
    Research target accounts with company insights and growth metrics.
  </Accordion>

  <Accordion title="Lead discovery" icon="users">
    Find new prospects matching your ICP using advanced filters.
  </Accordion>

  <Accordion title="Organizational mapping" icon="sitemap">
    Understand company structures and identify key stakeholders.
  </Accordion>

  <Accordion title="List synchronization" icon="rotate">
    Keep your CRM in sync with Sales Navigator saved searches.
  </Accordion>
</AccordionGroup>

***

## Rate limits

LinkedIn meters Sales Navigator per account on a rolling 24-hour window, and it meters groups of actions together rather than each action on its own. Cargo applies a matching daily limit per workspace so one workflow cannot exhaust the allowance every workspace shares.

| Limit              | Actions and models it covers                                                                                   |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| People search      | Search leads, Extract lead search, Search person metrics, Find company metrics, Fetch leads, Fetch lead search |
| Company search     | Search accounts, Extract account search, Search company metrics, Fetch accounts, Fetch account search          |
| Company enrichment | Find employees distribution, Find employees count                                                              |

Each limit allows **1,000 requests per 24 hours** per workspace.

The window rolls rather than resetting: allowance frees up gradually as requests fall out of the trailing 24 hours. Runs that exceed the limit fail with a message naming the limit reached and the usage against it. If your volume needs a higher limit, contact us.

Legacy actions and the Company insights action use a different provider and do not count against these limits.

***

## Best practices

1. **Use saved searches** - Create saved searches in Sales Navigator for efficient syncing
2. **Combine with enrichment** - Layer Sales Navigator data with other enrichment sources
3. **Spread large searches across days** - A search returns 25 leads per request, so a 10,000-lead list costs 400 requests against the people search limit; see [Rate limits](#rate-limits)


# Salesforce
Source: https://docs.getcargo.ai/integration/salesforce

This page outlines how to use the Salesforce integration to pull and manage CRM data in Cargo.

Salesforce is the world's leading enterprise CRM platform, powering sales, service, and marketing operations for businesses of all sizes. Cargo's native integration with Salesforce allows you to both pull data from the CRM as part of data models, and write or delete data from all CRM objects to maintain it.

## How to set up Salesforce

Salesforce uses OAuth to establish the sync with Cargo. During connection, you'll be asked to authorize Cargo.

Once redirected and the connector is created, you can:

* **Set up a Salesforce data model** — Create data models from your Salesforce objects to trigger Plays and power model search actions.
* **Use Salesforce in workflows** — Choose **Salesforce** from the node catalog within a **Play**, **Tool**, or **Agent**.

***

## Salesforce actions

<Tip>
  All Salesforce actions support Leads, Contacts, Accounts, Opportunities,
  Cases, and any custom objects you've created in your Salesforce org.
</Tip>

### Insert record

Insert a new record into Salesforce.

**Use cases**

* **Lead capture** – Create new leads from various sources and channels
* **Contact creation** – Add new contacts from forms, events, or imports
* **Opportunity creation** – Create new opportunities to track deals through your pipeline

### Find record

Retrieve a single record from Salesforce by its unique ID.

**Use cases**

* **Record lookup** – Get specific record details for processing workflows
* **Data validation** – Verify record existence before performing operations

### Match record

Check if a record exists in Salesforce based on matching criteria.

**Use cases**

* **Duplicate prevention** – Avoid creating duplicate records
* **Smart routing** – Route records based on existing data

<Info>
  Use **Match record** before **Insert record** to implement an upsert pattern
  for single records.
</Info>

### Find records

Find records matching the given criteria. Define multiple matching criteria—the action searches for records that match any of the provided values. Empty values are automatically skipped.

**Use cases**

* **Multi-identifier matching** – Search by domain, LinkedIn URL, or company name
* **Flexible lookups** – Find records using whichever identifiers are available
* **Data quality handling** – Provide multiple identifiers to maximize match rates

**Example configuration**

| Field      | Value                            |
| ---------- | -------------------------------- |
| `Website`  | `{{nodes.start.company_domain}}` |
| `LinkedIn` | `{{nodes.start.linkedin_url}}`   |
| `Name`     | `{{nodes.start.company_name}}`   |

<Tip>
  Empty values are automatically skipped, so you can provide all available identifiers without worrying about null checks.
</Tip>

### Search records

Retrieve multiple records from Salesforce using SOQL-based search criteria.

**Use cases**

* **Advanced filtering** – Find records meeting specific criteria
* **Bulk operations** – Retrieve multiple records for processing inside a group node
* **Cross-object queries** – Search across related objects using Salesforce relationships

### Update record

Update an existing record in Salesforce.

**Use cases**

* **Data enrichment** – Keep record information current and accurate
* **Lifecycle management** – Update lead status, opportunity stages, and case statuses
* **Field updates** – Modify any standard or custom field values

### Upsert records

Upsert multiple records into Salesforce (insert or update based on external ID or matching criteria).

**Use cases**

* **Bulk data operations** – Insert records in bulk while avoiding duplicates
* **Data synchronization** – Keep external systems synchronized with Salesforce
* **Migration workflows** – Import data from other systems using external IDs

<Warning>
  Upsert operations in Salesforce require an external ID field for matching.
  Ensure your matching criteria is unique to avoid unintended updates.
</Warning>

### Delete record

Delete a record from Salesforce.

**Use cases**

* **Data cleanup** – Remove outdated or incorrect records programmatically or in batches

***

## Salesforce data models

Cargo allows you to create data models on top of your Salesforce CRM data that can be used to trigger Plays and power model search actions.

### Creating Salesforce data models

| Field           | Description                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Name**        | Choose a descriptive name for your data model (required)                                                                 |
| **Slug**        | Set a unique identifier that cannot be changed once created (required)                                                   |
| **Object Type** | Select the Salesforce object type you want to model (Leads, Contacts, Accounts, Opportunities, Cases, or custom objects) |

### Object types available

<AccordionGroup>
  <Accordion title="Lead models" icon="user-plus">
    **Use cases** - Handle inbound and outbound lead information - Track lead
    sources, campaigns, and conversion paths - Manage lead qualification and
    scoring workflows
  </Accordion>

  <Accordion title="Contact models" icon="user">
    **Use cases** - Manage contact records associated with accounts - Track
    individual engagement and communication history - Handle multi-contact
    relationships within accounts
  </Accordion>

  <Accordion title="Account models" icon="building">
    **Use cases** - Manage company and organization records - Track account
    hierarchies and parent-child relationships - Monitor account health scores
    and engagement metrics
  </Accordion>

  <Accordion title="Opportunity models" icon="handshake">
    **Use cases** - Track deals through pipeline stages - Monitor forecasting,
    close dates, and deal amounts - Analyze win rates and sales cycle metrics
  </Accordion>

  <Accordion title="Case models" icon="ticket">
    **Use cases** - Track customer support cases and issues - Monitor case
    resolution times and escalation paths - Analyze support trends and agent
    performance
  </Accordion>
</AccordionGroup>

<Tip>
  You can also model any **custom objects** you've created in Salesforce, giving
  you full flexibility to work with your unique data structures.
</Tip>


# Salesforce MCP
Source: https://docs.getcargo.ai/integration/salesforce-mcp

Connect a Salesforce hosted MCP server so your AI agents can use Salesforce tools.

Salesforce MCP connects a Salesforce hosted MCP (Model Context Protocol) server to Cargo so [AI agents](/agents/tools-and-actions#mcp-servers) can call Salesforce tools directly. It is separate from the regular [Salesforce](/integration/salesforce) CRM connection: each Salesforce org exposes its own MCP server URL, and authorization uses an **External Client App** you create in that org (`mcp_api` scope).

Salesforce does not support Dynamic Client Registration for hosted MCP, and an External Client App is not installed into another org on first OAuth (unlike a classic Connected App). Cargo therefore uses the same pattern as Claude, ChatGPT, Cursor, and Postman: you create the app in **your** org and paste its consumer key and secret into Cargo.

## How to set up Salesforce MCP

### 1. Activate a hosted MCP server

In Salesforce **Setup > MCP Servers**, open the **Salesforce Servers** tab, activate a server, and copy its **Server URL**. Production and sandbox URLs differ (`/platform/mcp/v1/` vs `/platform/mcp/v1/sandbox/`).

### 2. Create an External Client App

Connected Apps are not supported for MCP. In the **same org** as the server URL:

1. **Setup > Quick Find > External Client App Manager > New External Client App**
2. Set **Distribution State** to **Local** (not Packaged)
3. Enable OAuth and configure:
   * **Callback URL:** `https://app.getcargo.io/oauth-callback` (Cargo also shows this on the connector form)
   * **Scopes:** Access MCP servers (`mcp_api`) and Perform requests at any time (`refresh_token` / `offline_access`)
   * **Issue JWT-based access tokens for named users:** on
   * **Require PKCE:** on
   * **Require Secret for Web Server Flow:** on
4. Save, then copy the **Consumer Key** and **Consumer Secret** from the app's OAuth settings

A new External Client App can take up to **30 minutes** to become usable. See Salesforce's [Create an External Client App](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/create-external-client-app.html) guide.

### 3. Connect in Cargo

1. Create a **Salesforce MCP** connector
2. Turn on **Use sandbox?** if the org is a sandbox or scratch org
3. Paste the **MCP Server URL**, **Consumer Key**, and **Consumer Secret**
4. Click **Authorize Salesforce MCP** and sign in to **that** org
5. Cargo stores the resulting token and refreshes it automatically

<Note>
  **Code slugs** — integration slug: `salesforceMcp`. This integration exposes
  no fixed actions: its tools are discovered from your org's MCP server at
  runtime and made available to agents.
</Note>

## Salesforce MCP tools

The connector does not define static actions. When attached to an agent as an MCP server, the agent lists the tools your Salesforce MCP server advertises at runtime and can call any of them. See [MCP servers](/agents/tools-and-actions#mcp-servers) for how agents use MCP tools.

Related MCP integrations: [HubSpot MCP](/integration/hubspot-mcp) and [Notion MCP](/integration/notion-mcp).

## Best practices

* Use Salesforce MCP for agent tool use; keep the regular [Salesforce](/integration/salesforce) connector for workflow actions and data syncing
* Create the External Client App in the same org you authorize with — the server URL is org-specific
* Authorize with a Salesforce user whose permissions match what you want agents to be able to do
* If Salesforce returns `OAUTH_EC_APP_NOT_FOUND`, the consumer key does not belong to the org you logged into (wrong org, or the app is Packaged but not installed)


# Salesloft
Source: https://docs.getcargo.ai/integration/salesloft

Connect Salesloft to manage sales engagement, accounts, and people in your workflows.

## How to set up Salesloft

### Authentication

Salesloft uses API key authentication:

1. Log in to your Salesloft account
2. Navigate to **Settings** → **Integrations** → **API**
3. Generate a new API key
4. Copy the API key and paste it in Cargo when connecting

## Salesloft actions

### Insert account

Create a new account in Salesloft.

**Required fields:**

* **Name**: Account name
* **Domain**: Account domain

**Optional fields:**

* **Mappings**: Map additional standard fields
* **Custom mappings**: Map custom fields defined in your Salesloft instance

**Use case:** Automatically create accounts when new companies are identified from inbound leads.

### Insert person

Create a new person in Salesloft.

**Required fields:**

* **Email**: Person's email address

**Optional fields:**

* **Mappings**: Map additional standard fields
* **Custom mappings**: Map custom fields

**Use case:** Add new leads directly to Salesloft for sales outreach.

### Update account

Update an existing account by ID.

**Required fields:**

* **ID**: Salesloft account ID
* **Name**: Account name
* **Domain**: Account domain

**Optional fields:**

* **Mappings**: Fields to update
* **Custom mappings**: Custom fields to update

### Update person

Update an existing person by ID.

**Required fields:**

* **ID**: Salesloft person ID

**Optional fields:**

* **Mappings**: Fields to update
* **Custom mappings**: Custom fields to update

### Upsert account

Create a new account or update if it exists (matched by domain).

**Required fields:**

* **Name**: Account name
* **Domain**: Account domain

**Use case:** Keep account data synchronized between systems without creating duplicates.

### Upsert person

Create a new person or update if exists (matched by email).

**Required fields:**

* **Email**: Person's email address

**Use case:** Sync contact information from your CRM or marketing tools to Salesloft.

### Delete account

Remove an account from Salesloft.

**Required fields:**

* **ID**: Salesloft account ID

### Delete person

Remove a person from Salesloft.

**Required fields:**

* **ID**: Salesloft person ID

### Add person to cadence

Enroll a person into a Salesloft cadence for automated outreach.

**Required fields:**

* **Person ID**: The Salesloft person ID
* **Cadence**: Select the cadence to add them to

**Optional fields:**

* **User**: Assign to a specific sales rep

**Use case:** Automatically enroll qualified leads into sales sequences based on scoring or behavior.

### Remove person from cadence

Remove a person from an active cadence.

**Required fields:**

* **ID**: The cadence membership ID

## Rate limits

Salesloft API has a rate limit of 600 requests per minute. Cargo automatically handles rate limiting to ensure your workflows run smoothly.


# Scrubby
Source: https://docs.getcargo.ai/integration/scrubby

Verify email addresses with Scrubby

Scrubby is an email verification service that validates email addresses to improve deliverability and reduce bounce rates.

## Authentication

Connect to Scrubby using your API key.

### Connection details

| Field       | Description          |
| ----------- | -------------------- |
| **API Key** | Your Scrubby API key |

***

## Scrubby actions

### Verify email

Validate an email address to check if it's deliverable.

**Configuration**

| Field     | Description             |
| --------- | ----------------------- |
| **Email** | Email address to verify |

**Returns**

| Field      | Description                         |
| ---------- | ----------------------------------- |
| Status     | Deliverable, undeliverable, risky   |
| Risk level | Assessment of email risk            |
| Details    | Additional verification information |

***

## Use cases

<AccordionGroup>
  <Accordion title="List cleaning" icon="broom">
    Verify email lists before outreach to reduce bounces.
  </Accordion>

  <Accordion title="Lead validation" icon="check-circle">
    Validate leads at point of capture to ensure data quality.
  </Accordion>

  <Accordion title="Deliverability optimization" icon="envelope-circle-check">
    Improve email deliverability by removing invalid addresses.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Verify before sending** - Always verify emails before adding to outreach campaigns
2. **Handle risky emails** - Consider removing or isolating risky email addresses
3. **Cache results** - Verification results are cached to avoid redundant lookups


# SendGrid
Source: https://docs.getcargo.ai/integration/sendgrid

This page outlines how to use the SendGrid integration for transactional email in Cargo.

SendGrid is a cloud-based email delivery platform that helps businesses send transactional and marketing emails at scale. Cargo's native integration with SendGrid allows you to send templated emails directly from your workflows.

## How to set up SendGrid

To connect SendGrid, you'll need an API key from your SendGrid account.

### Connection details

| Field       | Description           |
| ----------- | --------------------- |
| **API Key** | Your SendGrid API key |

<Tip>Create an API key in SendGrid under **Settings → API Keys**. Ensure it has permission to send emails.</Tip>

Once the connector is created, you can:

* **Use SendGrid in workflows** — Choose **SendGrid** from the node catalog within a **Play**, **Tool**, or **Agent**.

***

## SendGrid actions

### Send email

Send an email using SendGrid's dynamic template system.

**Use cases**

* **Transactional emails** – Send order confirmations, receipts, notifications
* **Personalized outreach** – Send customized emails with dynamic content
* **Automated follow-ups** – Trigger emails based on workflow conditions

**Configuration**

| Field            | Description                            |
| ---------------- | -------------------------------------- |
| **Template**     | Select from your SendGrid templates    |
| **Subject**      | Email subject line                     |
| **From email**   | Sender email address                   |
| **From name**    | Sender display name                    |
| **To email**     | Recipient email address                |
| **Dynamic data** | Key-value pairs for template variables |

<Info>Templates are created and managed in SendGrid. Use dynamic data to populate template variables like `{{first_name}}` or `{{company}}`.</Info>

***

## Dynamic template data

SendGrid templates support dynamic variables that you can populate from your workflow data.

### Example configuration

| Key           | Value                   |
| ------------- | ----------------------- |
| `first_name`  | `{{contact.firstName}}` |
| `company`     | `{{contact.company}}`   |
| `meeting_url` | `{{calendar.link}}`     |

<Warning>Ensure your template variables match the keys you provide in dynamic data. Mismatched keys will result in empty values.</Warning>


# Serper
Source: https://docs.getcargo.ai/integration/serper

Connect Serper to search Google and find places in your workflows.

## How to set up Serper

### Authentication

Serper uses API key authentication:

1. Sign up at [serper.dev](https://serper.dev)
2. Navigate to your dashboard to find your API key
3. Copy the API key and paste it in Cargo when connecting

## Serper actions

### Search

Perform Google searches and retrieve results.

**Required fields:**

* **Query**: The search query (supports expressions)

**Optional fields:**

* **Country**: Filter results by country
* **Locale**: Language/locale for results
* **Limit**: Maximum number of results (default varies)

**Use cases:**

* Research companies by searching for news and press releases
* Find company information not available in enrichment tools
* Discover content and social profiles
* Validate company information

### Search places

Search for businesses and places on Google Maps.

**Required fields:**

* **Query**: The search query (e.g., "software companies in San Francisco")

**Optional fields:**

* **Country**: Filter by country
* **Locale**: Language/locale for results
* **Limit**: Maximum number of results

**Use cases:**

* Build lists of local businesses
* Find retail locations for account-based targeting
* Research competitors in specific markets
* Discover businesses by category and location

## Response data

### Search results include:

* Title
* Link (URL)
* Snippet (description)
* Position in results

### Places results include:

* Business name
* Address
* Phone number
* Rating
* Website
* Category

## Credits

Serper uses a credit-based system:

* Each search request costs 1 credit
* Credits are compatible with Cargo's credit tracking

## Best practices

* Use specific, targeted queries for better results
* Combine with other enrichment tools for complete profiles
* Cache results when possible to optimize credit usage
* Use country and locale filters for localized results


# Slack
Source: https://docs.getcargo.ai/integration/slack

This page outlines how to use the Slack integration to send messages and notifications from Cargo.

Slack is a leading business communication platform that brings teams together with real-time messaging, channels, and integrations. Cargo's native integration with Slack allows you to send messages, notifications, and alerts directly to channels or users as part of your workflows.

## How to set up Slack

Slack uses OAuth to establish the connection with Cargo. During connection, you'll be asked to authorize Cargo to access your Slack workspace.

Once redirected and the connector is created, you can:

* **Send messages from workflows** — Send notifications, alerts, and updates to Slack channels or users directly from your **Plays**, **Tools**, or **Agents**.
* **Keep teams informed** — Automate real-time notifications for important events like new leads, deal updates, or workflow completions.

***

## Slack actions

### Send message to channel

Post a message to a public or private Slack channel.

**Use cases**

* **Team notifications** – Alert your sales team when a high-value lead enters the pipeline
* **Deal updates** – Post to a deals channel when opportunities progress through stages
* **Workflow alerts** – Notify teams when automated workflows complete or require attention

<Tip>
  Use Slack's [Block Kit](https://api.slack.com/block-kit) formatting to create
  rich, interactive messages with buttons, sections, and more.
</Tip>

### Send direct message

Send a private message directly to a Slack user.

**Use cases**

* **Personal notifications** – Notify a specific rep when they're assigned a new lead
* **Task reminders** – Send individual reminders for follow-ups or pending actions
* **Escalations** – Alert managers directly when deals need attention

### Post threaded reply

Reply to an existing message in a thread.

**Use cases**

* **Conversation continuity** – Keep related updates organized in threads
* **Status updates** – Add progress updates to existing notification threads
* **Collaborative workflows** – Build context over time within a single thread

<Info>
  To post a threaded reply, you'll need the `thread_ts` (timestamp) of the
  parent message. This can be captured from a previous **Send message** action.
</Info>

***

## Message formatting

Slack supports rich text formatting using markdown-like syntax:

| Format            | Syntax          | Example                     |
| ----------------- | --------------- | --------------------------- |
| **Bold**          | `*text*`        | *important*                 |
| *Italic*          | `_text_`        | *emphasis*                  |
| ~~Strikethrough~~ | `~text~`        | ~~removed~~                 |
| `Code`            | `` `text` ``    | `variable`                  |
| Link              | `<url\|text>`   | `<https://cargo.io\|Cargo>` |
| User mention      | `<@USER_ID>`    | `<@U123ABC>`                |
| Channel mention   | `<#CHANNEL_ID>` | `<#C123ABC>`                |

<Warning>
  Ensure the Cargo app has been invited to private channels before attempting to
  post messages. The bot cannot access channels it hasn't been added to.
</Warning>


# Smartlead.ai
Source: https://docs.getcargo.ai/integration/smartlead

Connect Smartlead.ai to manage cold email campaigns and leads in your workflows.

## How to set up Smartlead.ai

### Authentication

Smartlead uses API key authentication:

1. Log in to your Smartlead.ai account
2. Navigate to **Settings** → **API**
3. Generate or copy your API key
4. Paste the API key in Cargo when connecting

## Smartlead actions

### Add lead

Add a new lead to a Smartlead campaign.

**Required fields:**

* **Campaign ID**: The ID of the campaign to add the lead to
* **Email**: Lead's email address

**Optional fields:**

* **Mappings**: Map standard lead fields:
  * First name
  * Last name
  * Phone number
  * Company name
  * Website
  * Location
  * LinkedIn profile
  * Company URL
* **Custom mappings**: Map custom fields for personalization

**Use cases:**

* Automatically enroll qualified leads into cold email campaigns
* Sync leads from your CRM to Smartlead campaigns
* Add leads based on scoring or segmentation criteria

### Pause lead

Temporarily pause a lead in a campaign.

**Required fields:**

* **Campaign ID**: The campaign the lead is in
* **Lead ID**: The Smartlead lead ID

**Use case:** Pause outreach when a lead shows engagement or requests to be contacted later.

### Resume lead

Resume a paused lead in a campaign.

**Required fields:**

* **Campaign ID**: The campaign the lead is in
* **Lead ID**: The Smartlead lead ID

**Use case:** Resume outreach after a specified time or based on a trigger.

### Remove lead

Remove a lead from a campaign entirely.

**Required fields:**

* **Campaign ID**: The campaign the lead is in
* **Lead ID**: The Smartlead lead ID

**Use case:** Remove leads who have converted, unsubscribed, or no longer match your criteria.

## Field mappings

When adding leads, you can map these standard fields:

| Field             | Description          |
| ----------------- | -------------------- |
| first\_name       | Contact's first name |
| last\_name        | Contact's last name  |
| phone\_number     | Phone number         |
| company\_name     | Company name         |
| website           | Company website      |
| location          | Geographic location  |
| linkedin\_profile | LinkedIn profile URL |
| company\_url      | Company website URL  |

## Rate limits

Smartlead API has a rate limit of 60 requests per minute. Cargo automatically handles rate limiting to ensure reliable delivery.


# Snitcher
Source: https://docs.getcargo.ai/integration/snitcher

Identify website visitors and track sessions with Snitcher

Snitcher is a website visitor identification platform that reveals which companies are visiting your website and tracks their browsing sessions. The Cargo integration enables you to sync visitor data and search sessions.

## Authentication

There are two ways to connect Snitcher to Cargo:

### Bring your own API key

If you already have a Snitcher account, connect using your API key. This gives you full control over your Snitcher workspace and billing.

| Field       | Description           |
| ----------- | --------------------- |
| **API key** | Your Snitcher API key |

You can find your API key in the [Snitcher dashboard](https://app.snitcher.com) under **Settings > API**.

### Use Cargo credits

If you don't have a Snitcher account, you can use Cargo credits instead. Cargo will automatically create and manage a Snitcher workspace for you — no API key required.

***

## Setting up the tracking script

To identify companies visiting your website, you need to install the Snitcher tracking script on your site. This script collects anonymous visitor data that Snitcher uses to match visits to companies.

### Step 1: Create a data model

1. In Cargo, create a new data model using the **Snitcher** integration
2. Select the **Fetch organisations** extractor
3. Choose your workspace (if using your own API key) or enter the website URL you want to track (if using Cargo credits)
4. Save the data model

### Step 2: Copy the tracking script

Once the data model is created, Cargo displays the tracking script snippet in the model settings. The script looks like this:

```html theme={null}
<script>
  !(function (s, n, i, t, c, h) {
    s.SnitchObject = i;
    s[i] ||
      (s[i] = function () {
        (s[i].q = s[i].q || []).push(arguments);
      });
    s[i].l = +new Date();
    c = n.createElement(t);
    h = n.getElementsByTagName(t)[0];
    c.src = "//snid.snitcher.com/YOUR_TRACKING_ID.js";
    h.parentNode.insertBefore(c, h);
  })(window, document, "snid", "script");

  snid("verify", "YOUR_TRACKING_ID");
</script>
```

`YOUR_TRACKING_ID` will be replaced with the actual tracking ID assigned to your workspace.

### Step 3: Install the script on your website

Add the tracking script to every page you want to track. Place it in the `<head>` section of your HTML, or use your tag manager.

<AccordionGroup>
  <Accordion title="Direct HTML" icon="code">
    Paste the script inside the `<head>` tag of your website's HTML:

    ```html theme={null}
    <head>
      <!-- Other head tags -->
      <script>
        !(function (s, n, i, t, c, h) {
          s.SnitchObject = i;
          s[i] || (s[i] = function () { (s[i].q = s[i].q || []).push(arguments); });
          s[i].l = +new Date();
          c = n.createElement(t);
          h = n.getElementsByTagName(t)[0];
          c.src = "//snid.snitcher.com/YOUR_TRACKING_ID.js";
          h.parentNode.insertBefore(c, h);
        })(window, document, "snid", "script");
        snid("verify", "YOUR_TRACKING_ID");
      </script>
    </head>
    ```
  </Accordion>

  <Accordion title="Google Tag Manager" icon="tag">
    1. Open [Google Tag Manager](https://tagmanager.google.com)
    2. Create a new **Custom HTML** tag
    3. Paste the tracking script into the HTML field
    4. Set the trigger to **All Pages**
    5. Publish the container
  </Accordion>

  <Accordion title="Next.js / React" icon="react">
    Add the script using the Next.js `Script` component or a regular `<script>` tag in your layout:

    ```jsx theme={null}
    import Script from "next/script";

    export default function Layout({ children }) {
      return (
        <html>
          <head />
          <body>
            {children}
            <Script
              id="snitcher-tracking"
              strategy="afterInteractive"
              dangerouslySetInnerHTML={{
                __html: `
                  !(function (s, n, i, t, c, h) {
                    s.SnitchObject = i;
                    s[i] || (s[i] = function () { (s[i].q = s[i].q || []).push(arguments); });
                    s[i].l = +new Date();
                    c = n.createElement(t);
                    h = n.getElementsByTagName(t)[0];
                    c.src = "//snid.snitcher.com/YOUR_TRACKING_ID.js";
                    h.parentNode.insertBefore(c, h);
                  })(window, document, "snid", "script");
                  snid("verify", "YOUR_TRACKING_ID");
                `,
              }}
            />
          </body>
        </html>
      );
    }
    ```
  </Accordion>
</AccordionGroup>

### Step 4: Verify the installation

Once the script is installed, visit your website and check back in Cargo after a few minutes. New visitor data should start appearing in your Snitcher data model. You can also verify the script is loading correctly by opening your browser's developer tools (Network tab) and looking for a request to `snid.snitcher.com`.

<Note>
  It may take up to 30 minutes for the first organisations to appear after installing the tracking script. Snitcher fetches new data incrementally every 30 minutes.
</Note>

***

## Snitcher actions

### Search sessions

Search and retrieve website visitor sessions with filtering options.

**Configuration**

| Field                 | Description                           |
| --------------------- | ------------------------------------- |
| **URL**               | The website URL you are tracking      |
| **Organisation UUID** | Filter by specific organization       |
| **Date from**         | Start date for filtering sessions     |
| **Date to**           | End date for filtering sessions       |
| **URL contains**      | Filter sessions by URL substring      |
| **Referrer contains** | Filter sessions by referrer substring |
| **Limit**             | Maximum records to retrieve           |

***

## Data models

### Fetch organisations

Track companies that visit your website.

**Configuration**

| Field         | Description              |
| ------------- | ------------------------ |
| **Workspace** | The workspace to track   |
| **URL**       | The website URL to track |

**Data returned**

Each organization includes company details, website, and visit metrics.

### Fetch sessions

Track individual website sessions and visitor activity.

**Configuration**

| Field   | Description                      |
| ------- | -------------------------------- |
| **URL** | The website URL you are tracking |

***

## Credits

| Action/Extractor    | Cost                 |
| ------------------- | -------------------- |
| Search sessions     | Free                 |
| Fetch organisations | 3 credits per record |
| Fetch sessions      | Free                 |

***

## Use cases

<AccordionGroup>
  <Accordion title="Account-based marketing" icon="bullseye">
    Identify target accounts visiting your website and trigger campaigns.
  </Accordion>

  <Accordion title="Session analysis" icon="chart-line">
    Understand visitor behavior by analyzing session data.
  </Accordion>

  <Accordion title="Lead scoring" icon="star">
    Boost lead scores based on website engagement patterns.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Install the script on all pages** - The more pages you track, the better Snitcher can identify visitor intent
2. **Track high-value pages** - Pay special attention to visitors on pricing, demo, or product pages
3. **Use date filters** - Filter sessions to analyze specific time periods
4. **Combine with CRM data** - Match visitor data with existing account records


# Snov.io
Source: https://docs.getcargo.ai/integration/snov

Connect Snov.io to find emails, verify addresses, and enrich profiles in your workflows.

## How to set up Snov.io

### Authentication

Snov.io uses OAuth client credentials:

1. Log in to your Snov.io account
2. Navigate to **Integrations** → **API**
3. Find your Client ID and Client Secret
4. Enter both credentials in Cargo when connecting

## Snov.io actions

### Find email

Find a person's email address using their name and company domain.

**Required fields:**

* **Domain**: Company domain (e.g., "snov.io")
* **First name**: Person's first name
* **Last name**: Person's last name

**Use cases:**

* Find professional emails for outbound prospecting
* Enrich leads with email addresses
* Build contact lists from company domains

### Verify email

Check if an email address is valid and deliverable.

**Required fields:**

* **Email**: The email address to verify

**Verification statuses:**

* Valid - Email exists and is deliverable
* Invalid - Email doesn't exist or bounces
* Catch-all - Domain accepts all emails (can't verify)
* Unknown - Couldn't determine status

**Use case:** Clean your email lists before sending campaigns to improve deliverability.

### Enrich profile

Get detailed information about a person using their email address.

**Required fields:**

* **Email**: The person's email address

**Returns:**

* Full name
* Job title
* Company information
* Social profiles
* Location data

**Use case:** Enrich existing contacts with additional profile data.

### Search profiles

Find prospects at a company by domain and job titles.

**Required fields:**

* **Domain**: Company domain to search
* **Positions**: Job titles to filter by (up to 10)

**Use cases:**

* Find decision makers at target companies
* Build account-based prospect lists
* Discover contacts by role and company

## Response data

### Find email returns:

| Field       | Description         |
| ----------- | ------------------- |
| email       | Found email address |
| status      | Verification status |
| first\_name | First name          |
| last\_name  | Last name           |
| position    | Job title           |

### Enrich profile returns:

| Field       | Description         |
| ----------- | ------------------- |
| name        | Full name           |
| first\_name | First name          |
| last\_name  | Last name           |
| position    | Current job title   |
| company     | Company name        |
| industry    | Industry            |
| country     | Country             |
| social      | Social profile URLs |

### Verify email returns:

| Field       | Description            |
| ----------- | ---------------------- |
| email       | Verified email address |
| status      | Verification status    |
| free\_email | Is it a free email?    |
| disposable  | Is it disposable?      |

## Best practices

* Always verify emails before sending campaigns
* Use specific job titles for better search results
* Combine find email with verification for quality
* Cache results to avoid duplicate lookups
* Use enrichment to fill gaps in contact data
* Filter out free/disposable emails for B2B outreach

## Retry behavior

Snov.io actions include automatic retry logic with exponential backoff to handle rate limits and temporary errors gracefully.


# Snowflake
Source: https://docs.getcargo.ai/integration/snowflake

This page outlines how to use the Snowflake integration to create and manage your data warehouse in Cargo.

Snowflake is a cloud-native data platform that provides fast, scalable data warehousing and analytics. Cargo's native integration with Snowflake allows you to use it as your system of record—powering data models, plays, and automated workflows.

<Note>
  To use Snowflake as your **system of record**, follow the full setup guide:
  [Set up Cargo on Snowflake](/reference/system-of-record/snowflake). It covers
  the required roles, RSA key authentication, IP allowlist, and the SOR
  settings form.
</Note>

## How to set up Snowflake

### Connecting your own Snowflake

To connect your existing Snowflake instance, you'll need:

* An active Snowflake account
* A dedicated database, warehouse, and user for Cargo
* Proper role permissions configured

### Connection details

To set up the connection, provide the following details when creating the connector:

| Field               | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| **Account**         | Your Snowflake account identifier                          |
| **Database**        | The database created for Cargo (e.g., `cargo_db`)          |
| **Warehouse**       | The warehouse for Cargo operations (e.g., `cargo_wh`)      |
| **Role**            | The role with appropriate permissions (e.g., `cargo_role`) |
| **User**            | The Cargo service user (e.g., `cargo_user`)                |
| **Password**        | The user's password (for password authentication)          |
| **RSA Private Key** | The user's private key (for RSA key pair authentication)   |

### Authentication methods

Cargo supports two authentication methods for Snowflake:

1. **Password authentication** – Use a username and password to connect
2. **RSA key pair authentication** – Use a public/private key pair for enhanced security

To use RSA key pair authentication, provide your private key instead of a password when configuring the connection. This method is recommended for production environments as it provides stronger security.

***

## Snowflake actions

Once connected, you can use Snowflake in your workflows with the following actions:

### Insert

Insert new records into a Snowflake table.

**Configuration**

| Field        | Description                                        |
| ------------ | -------------------------------------------------- |
| **Database** | The Snowflake database containing the target table |
| **Schema**   | The schema containing the target table             |
| **Table**    | The table to insert data into                      |
| **Mappings** | Map columns to values using expressions            |

**Use cases**

* **Lead capture** – Insert new leads from form submissions or enrichment workflows
* **Event logging** – Record workflow events and outcomes
* **Data aggregation** – Store computed results for reporting

### Update

Update existing records in a Snowflake table based on a matching column.

**Configuration**

| Field               | Description                                        |
| ------------------- | -------------------------------------------------- |
| **Database**        | The Snowflake database containing the target table |
| **Schema**          | The schema containing the target table             |
| **Table**           | The table to update                                |
| **Matching Column** | The column to match records against                |
| **Matching Value**  | The value to match (supports expressions)          |
| **Mappings**        | Map columns to new values using expressions        |

**Use cases**

* **Data enrichment** – Update records with enriched data from external sources
* **Status updates** – Mark records as processed or update stages
* **Sync external changes** – Keep Snowflake in sync with CRM or other systems

### Upsert

Create new records or update existing ones based on a matching column.

**Configuration**

| Field               | Description                                        |
| ------------------- | -------------------------------------------------- |
| **Database**        | The Snowflake database containing the target table |
| **Schema**          | The schema containing the target table             |
| **Table**           | The table to upsert into                           |
| **Matching Column** | The column to match records against                |
| **Matching Value**  | The value to match (supports expressions)          |
| **Mappings**        | Map columns to values using expressions            |

**Use cases**

* **Data sync** – Keep your warehouse updated regardless of whether records exist
* **Idempotent operations** – Safely retry operations without creating duplicates
* **Master data management** – Maintain a single source of truth

### Delete

Delete records from a Snowflake table based on a matching column.

**Configuration**

| Field               | Description                                        |
| ------------------- | -------------------------------------------------- |
| **Database**        | The Snowflake database containing the target table |
| **Schema**          | The schema containing the target table             |
| **Table**           | The table to delete from                           |
| **Matching Column** | The column to match records against                |
| **Matching Value**  | The value to match (supports expressions)          |

**Use cases**

* **Data cleanup** – Remove outdated or invalid records
* **GDPR compliance** – Delete personal data on request
* **Workflow automation** – Remove processed records from staging tables

***

## Snowflake data models

Cargo allows you to create data models on top of your Snowflake data that can be used to trigger Plays and power workflows.

### Creating Snowflake data models

To create a Snowflake data model:

1. Navigate to **Data Models** in Cargo
2. Click **Create data model**
3. Select **Snowflake** as the source
4. Configure the following fields:

| Field             | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| **Name**          | Choose a descriptive name for your model                    |
| **Slug**          | Set a unique identifier that cannot be changed once created |
| **Database**      | Select the Snowflake database containing your data          |
| **Schema**        | Select the schema containing your data                      |
| **Table**         | Select the table or view to model                           |
| **ID Column**     | The column containing unique record identifiers             |
| **Title Column**  | The column to display as the record title                   |
| **Cursor Column** | (Optional) Column for incremental syncing (date or number)  |

### Using Snowflake data models

Once created, your Snowflake data model can be used to:

* **Trigger Plays** – Start automated workflows when data changes
* **Power enrichment** – Use Snowflake data to enrich records in workflows
* **Create segments** – Filter and target specific records from your data

***

## Network configuration

If you're using Snowflake's Allowed IPs network policy, add these Cargo IP addresses to your whitelist:

* `3.251.34.134`
* `54.220.135.99`
* `79.125.105.52`

***

## Security

* All Snowflake connections are encrypted using SSL/TLS
* Credentials are securely stored and encrypted at rest
* Cargo supports RSA key-pair authentication for enhanced security
* Cargo never overwrites existing tables—it always creates its own


# Societe Info
Source: https://docs.getcargo.ai/integration/societe-info

Access French company and contact data with Societe Info

Societe Info is a B2B data platform specializing in French company information, providing detailed firmographic data, financials, and contact information.

## Authentication

Connect to Societe Info using your API key.

### Connection details

| Field       | Description               |
| ----------- | ------------------------- |
| **API key** | Your Societe Info API key |

***

## Societe Info actions

### Enrich

Retrieve detailed information about a company or contact.

**Object types**

| Type        | Description                      |
| ----------- | -------------------------------- |
| **Company** | Enrich company by various fields |
| **Contact** | Enrich contact by various fields |

**Company enrich fields**

| Field               | Description                     |
| ------------------- | ------------------------------- |
| Name                | Company name                    |
| Street              | Street address                  |
| Postal code         | Postal code                     |
| City                | City                            |
| Domain name         | Domain or website URL           |
| Email               | Email address                   |
| First/Last name     | Representative's name           |
| LinkedIn URL        | Company or profile LinkedIn URL |
| Registration number | SIREN/SIRET number              |

**Contact enrich fields**

| Field               | Description              |
| ------------------- | ------------------------ |
| First/Last name     | Contact's name           |
| Full name           | First name and last name |
| Company name        | Company name             |
| Domain name         | Domain or website URL    |
| Email               | Email address            |
| LinkedIn URL        | LinkedIn profile URL     |
| Registration number | Company SIREN/SIRET      |

### Search

Search for companies or contacts with advanced filtering.

**Company search filters**

| Filter Category  | Available Filters                         |
| ---------------- | ----------------------------------------- |
| **Basic**        | Query, search mode, page number           |
| **Location**     | Place ID, postal code, city               |
| **Industry**     | NAF codes (include/exclude)               |
| **Financials**   | Sales range, profits range                |
| **Size**         | Staff count range                         |
| **Dates**        | Creation date, CEO birthdate              |
| **Social**       | LinkedIn followers range                  |
| **Data quality** | Has website, phone, email, LinkedIn, etc. |

**Contact search filters**

| Filter             | Description                |
| ------------------ | -------------------------- |
| **SIREN**          | Company SIREN (required)   |
| **Contact level**  | Responsibility level codes |
| **Contact domain** | Activity domain codes      |
| **Contact role**   | Semantic query on roles    |

***

## Credits

| Action | Cost                 |
| ------ | -------------------- |
| Enrich | 4 credits            |
| Search | 4 credits per result |

***

## Use cases

<AccordionGroup>
  <Accordion title="French market research" icon="flag">
    Build targeted lists of French companies by industry and size.
  </Accordion>

  <Accordion title="Financial analysis" icon="chart-line">
    Filter companies by revenue, profits, and growth metrics.
  </Accordion>

  <Accordion title="Contact discovery" icon="users">
    Find decision-makers at target French companies.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use SIREN** - The registration number provides the most accurate company matching
2. **Filter by data quality** - Use withEmail, withPhone filters to ensure actionable data
3. **Leverage financial filters** - Target companies in specific revenue ranges


# SQL
Source: https://docs.getcargo.ai/integration/sql

Connect to SQL databases for direct data access and manipulation

The SQL integration allows you to connect directly to SQL databases, enabling you to fetch data from tables or custom queries, and perform CRUD operations on your data.

## Authentication

SQL connections are configured through your warehouse connections (Snowflake, BigQuery, or Redshift). No additional authentication is required.

***

## SQL actions

### Search records

Retrieve multiple records from a table with filtering and sorting.

**Configuration**

| Field        | Description                                |
| ------------ | ------------------------------------------ |
| **Database** | The database name                          |
| **Schema**   | The schema name                            |
| **Table**    | The table name                             |
| **Filter**   | Define filter conditions                   |
| **Sort**     | Sort results                               |
| **Limit**    | Maximum records to retrieve (default: 100) |

### Insert record

Insert a new record into a table.

**Configuration**

| Field        | Description       |
| ------------ | ----------------- |
| **Database** | The database name |
| **Schema**   | The schema name   |
| **Table**    | The table name    |
| **Mappings** | Map column values |

### Update records

Update existing records in a table.

**Configuration**

| Field               | Description            |
| ------------------- | ---------------------- |
| **Database**        | The database name      |
| **Schema**          | The schema name        |
| **Table**           | The table name         |
| **Matching Value**  | Value to match against |
| **Matching column** | Column to match on     |
| **Mappings**        | Map columns to update  |

### Upsert records

Insert or update records based on a matching column.

**Configuration**

| Field               | Description            |
| ------------------- | ---------------------- |
| **Database**        | The database name      |
| **Schema**          | The schema name        |
| **Table**           | The table name         |
| **Matching Value**  | Value to match against |
| **Matching column** | Column to match on     |
| **Mappings**        | Map column values      |

### Delete records

Delete records from a table.

**Configuration**

| Field               | Description            |
| ------------------- | ---------------------- |
| **Database**        | The database name      |
| **Schema**          | The schema name        |
| **Table**           | The table name         |
| **Matching Value**  | Value to match against |
| **Matching column** | Column to match on     |

<Warning>
  Delete operations are permanent. Ensure you have proper filters configured.
</Warning>

***

## Data models

### Fetch table

Create data models directly from database tables.

**Configuration**

| Field        | Description                             |
| ------------ | --------------------------------------- |
| **Database** | The database name                       |
| **Schema**   | The schema name                         |
| **Table**    | The table name                          |
| **ID**       | Column containing unique record IDs     |
| **Title**    | Column containing record display titles |

### Fetch query

Create data models from custom SQL queries.

**Configuration**

| Field     | Description                             |
| --------- | --------------------------------------- |
| **SQL**   | The SQL query to execute                |
| **ID**    | Column containing unique record IDs     |
| **Title** | Column containing record display titles |

<Tip>
  Use fetch query for complex joins, aggregations, or filtered views of your
  data.
</Tip>

***

## Best practices

1. **Index your columns** - Ensure columns used in filters and joins are properly indexed
2. **Limit result sets** - Always use appropriate limits to avoid pulling excessive data
3. **Use views for complex queries** - Consider creating database views for frequently used complex queries


# Store Leads
Source: https://docs.getcargo.ai/integration/storeleads

Enrich e-commerce store data with Store Leads

Store Leads is a B2B data platform focused on e-commerce stores, providing detailed information about online retailers including technologies used, platform data, and company details.

## Authentication

Connect to Store Leads using your API key.

### Connection details

| Field       | Description              |
| ----------- | ------------------------ |
| **API Key** | Your Store Leads API key |

***

## Store Leads actions

### Enrich domain

Retrieve detailed information about an e-commerce store.

**Configuration**

| Field      | Description                   |
| ---------- | ----------------------------- |
| **Domain** | Domain of the store to enrich |

**Returns**

| Data Type           | Description                              |
| ------------------- | ---------------------------------------- |
| Company details     | Name, location, contact information      |
| E-commerce platform | Shopify, WooCommerce, Magento, etc.      |
| Technologies        | Payment processors, analytics, marketing |
| Store metrics       | Estimated traffic, product count         |

***

## Data models

### Listen list

Receive data from Store Leads lists directly into Cargo.

**Configuration**

No additional configuration required. Store Leads will push list data to Cargo automatically.

***

## Use cases

<AccordionGroup>
  <Accordion title="E-commerce prospecting" icon="store">
    Build targeted lists of online stores using specific platforms or technologies.
  </Accordion>

  <Accordion title="Technology targeting" icon="microchip">
    Find stores using specific payment processors, analytics tools, or marketing platforms.
  </Accordion>

  <Accordion title="Competitive analysis" icon="chart-bar">
    Research competitor stores and their technology stacks.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Filter by platform** - Focus on stores using platforms relevant to your product
2. **Technology signals** - Target stores based on complementary or competing technologies
3. **Combine with enrichment** - Layer Store Leads data with contact enrichment for outreach


# Stripe
Source: https://docs.getcargo.ai/integration/stripe

This page outlines how to use the Stripe integration to manage payment data in Cargo.

Stripe is a leading payment processing platform that powers online transactions for millions of businesses. Cargo's native integration with Stripe allows you to manage customers, search for payment data, and sync financial information directly from your workflows.

## How to set up Stripe

To connect Stripe, you'll need a Secret Key from your Stripe account.

### Connection details

| Field          | Description                |
| -------------- | -------------------------- |
| **Secret Key** | Your Stripe Secret API Key |

<Warning>
  Use your test mode secret key for development and your live mode secret key
  for production. Never expose your secret key publicly.
</Warning>

Once the connector is created, you can:

* **Set up Stripe data models** — Create data models from your Stripe customers, invoices, or subscriptions to trigger Plays.
* **Use Stripe in workflows** — Choose **Stripe** from the node catalog within a **Play**, **Tool**, or **Agent**.

***

## Stripe actions

### Search customers

Retrieve customer records based on filter criteria.

**Use cases**

* **Customer lookup** – Find customers by email, name, or metadata
* **Segmentation** – Retrieve customers matching specific criteria
* **Reporting** – Pull customer data for analysis

**Configuration**

| Field      | Description                                         |
| ---------- | --------------------------------------------------- |
| **Filter** | Define filter conditions to match customers         |
| **Limit**  | Maximum records to retrieve (default: 10, max: 100) |

### Search products

Retrieve product records based on filter criteria.

**Use cases**

* **Product catalog** – Search for products by name or attributes
* **Pricing analysis** – Find products matching pricing criteria

### Search invoices

Retrieve invoice records based on filter criteria.

**Use cases**

* **Invoice lookup** – Find invoices by status, customer, or date
* **Revenue analysis** – Pull invoice data for reporting
* **Collections** – Find overdue invoices for follow-up

### Search subscriptions

Retrieve subscription records based on filter criteria.

**Use cases**

* **Subscription management** – Find active or canceled subscriptions
* **Churn analysis** – Identify subscriptions at risk
* **Upgrade opportunities** – Find subscriptions eligible for upgrades

### Get customer

Retrieve a single customer by ID.

**Use cases**

* **Customer details** – Fetch full customer data for workflows
* **Conditional logic** – Make decisions based on customer attributes

**Configuration**

| Field  | Description            |
| ------ | ---------------------- |
| **ID** | The Stripe customer ID |

### Get subscription

Retrieve a single subscription by ID.

**Configuration**

| Field  | Description                |
| ------ | -------------------------- |
| **ID** | The Stripe subscription ID |

### Cancel subscription

Cancel an active subscription by ID.

**Use cases**

* **Customer offboarding** – End a subscription when a customer requests cancellation
* **Failed payment workflows** – Cancel subscriptions after repeated payment failures
* **Plan lifecycle management** – Programmatically stop subscriptions from Cargo workflows

**Configuration**

| Field  | Description                |
| ------ | -------------------------- |
| **ID** | The Stripe subscription ID |

<Warning>
  This action cancels the subscription immediately in Stripe.
</Warning>

### Get invoice

Retrieve a single invoice by ID.

**Configuration**

| Field  | Description           |
| ------ | --------------------- |
| **ID** | The Stripe invoice ID |

### Get product

Retrieve a single product by ID.

**Configuration**

| Field  | Description           |
| ------ | --------------------- |
| **ID** | The Stripe product ID |

### Insert customer

Create a new customer in Stripe.

**Use cases**

* **Customer creation** – Create customers from your CRM or signup flows
* **Pre-checkout** – Create customers before they complete payment

**Configuration**

| Field        | Description                              |
| ------------ | ---------------------------------------- |
| **Mappings** | Map Stripe customer properties to values |

### Upsert customers

Create new customers or update existing ones based on matching criteria.

**Use cases**

* **Data sync** – Sync customer data from your CRM
* **Avoid duplicates** – Ensure customers aren't duplicated
* **Customer enrichment** – Update customers with additional data

**Configuration**

| Field                      | Description                              |
| -------------------------- | ---------------------------------------- |
| **Matching Property Name** | The property to match on                 |
| **Matching Value**         | The value to match against               |
| **Mappings**               | Map Stripe customer properties to values |
| **Skip if exist**          | Update property only if it's empty       |

### Update customers

Update existing customer records.

**Use cases**

* **Data enrichment** – Update customers with enriched information
* **Metadata updates** – Add or update customer metadata
* **Address updates** – Update billing or shipping addresses

**Configuration**

| Field                      | Description                              |
| -------------------------- | ---------------------------------------- |
| **Matching Property Name** | The property to match on                 |
| **Matching Value**         | The value to match against               |
| **Mappings**               | Map Stripe customer properties to values |
| **Skip if exist**          | Update property only if it's empty       |

### Delete customers

Delete customer records from Stripe.

**Use cases**

* **GDPR compliance** – Delete customer data upon request
* **Data cleanup** – Remove test or invalid customers

**Configuration**

| Field                      | Description                |
| -------------------------- | -------------------------- |
| **Matching Property Name** | The property to match on   |
| **Matching Value**         | The value to match against |

<Warning>
  Deleting a Stripe customer is permanent. This will cancel all subscriptions
  and remove all payment methods associated with the customer.
</Warning>

***

## Stripe data models

Cargo allows you to create data models on top of your Stripe data that can be used to trigger Plays and power workflows.

### Available extractors

<AccordionGroup>
  <Accordion title="Fetch customers" icon="users">
    Pull customer records from Stripe with incremental sync support.

    **Use cases**

    * Build data models from your Stripe customers
    * Trigger workflows when customers are created or updated
    * Power customer lifecycle workflows
  </Accordion>

  <Accordion title="Fetch invoices" icon="file-invoice-dollar">
    Pull invoice records from Stripe with incremental sync support.

    **Use cases**

    * Track invoice status and payments
    * Trigger collection workflows for overdue invoices
    * Build revenue analytics
  </Accordion>

  <Accordion title="Fetch subscriptions" icon="repeat">
    Pull subscription records from Stripe with incremental sync support.

    **Use cases**

    * Track subscription lifecycle
    * Trigger workflows on subscription changes
    * Monitor churn and retention
  </Accordion>

  <Accordion title="Fetch products" icon="box">
    Pull product records from Stripe with incremental sync support.

    **Use cases**

    * Maintain product catalog data
    * Track product changes
  </Accordion>

  <Accordion title="Fetch plans" icon="list">
    Pull plan records from Stripe with incremental sync support.

    **Use cases**

    * Track pricing plan data
    * Monitor plan usage
  </Accordion>
</AccordionGroup>


# Sumble
Source: https://docs.getcargo.ai/integration/sumble

Connect Sumble to discover companies, jobs, and people by technology stack in your workflows.

Sumble provides technology intelligence data to help you find organizations, jobs, and people based on technology stack information. It builds a knowledge graph from web data—like job posts and resume data—to identify org structure, tech stack, and key projects.

## How to set up Sumble

### Authentication

Sumble uses API key authentication:

1. Sign up at [sumble.com](https://sumble.com)
2. Navigate to your API settings to get your API key
3. Paste the API key in Cargo when connecting

***

## Sumble actions

### Find organizations

Search for organizations matching technology filters.

**Parameters:**

| Filter                | Description                                                                   |
| --------------------- | ----------------------------------------------------------------------------- |
| Technologies          | Filter by technologies (e.g., python, react). Returns orgs using any of these |
| Technology categories | Filter by category (e.g., cybersecurity)                                      |
| Since                 | Only return organizations with activity since this date (YYYY-MM-DD)          |
| Order by              | Sort results by industry, employee count, activity time, jobs count, etc.     |
| Order direction       | Ascending or descending                                                       |
| Limit                 | Maximum records to retrieve (default: 10, max: 200)                           |

**Use cases:**

* **Technographic targeting** – Find companies using specific technologies
* **Competitive analysis** – Identify organizations adopting competitor tech stacks
* **Market research** – Discover companies in specific technology categories

### Enrich organization

Get detailed technology data for a specific organization by domain.

**Parameters:**

| Parameter             | Description                                     |
| --------------------- | ----------------------------------------------- |
| Organization domain   | The domain to enrich (e.g., sumble.com)         |
| Technologies          | Filter technologies returned (optional)         |
| Technology categories | Filter by technology category (optional)        |
| Since                 | Only include technologies found since this date |

**Returns:**

* Organization details
* Technologies found and count
* Source data URL

**Use cases:**

* **Account enrichment** – Add technographic data to existing accounts
* **Lead scoring** – Score leads based on technology stack alignment
* **Personalization** – Tailor outreach based on technologies in use

### Find jobs

Search for job listings at a specific organization based on technology requirements.

**Parameters:**

| Parameter             | Description                                               |
| --------------------- | --------------------------------------------------------- |
| Organization domain   | The domain to search jobs for                             |
| Technologies          | Filter by technologies mentioned in jobs                  |
| Technology categories | Filter by technology category                             |
| Since                 | Only include jobs with technologies found since this date |
| Limit                 | Maximum records to retrieve (default: 10, max: 100)       |

**Use cases:**

* **Hiring signals** – Identify companies actively hiring for specific tech roles
* **Expansion tracking** – Monitor when target accounts are growing teams
* **Tech adoption signals** – Spot new technology adoption through job requirements

### Find people

Find people at an organization with optional job function and level filters.

**Parameters:**

| Parameter           | Description                                              |
| ------------------- | -------------------------------------------------------- |
| Organization domain | The domain to search people for                          |
| Job functions       | Filter by function (e.g., Software Engineer, Operations) |
| Job levels          | Filter by level (e.g., Individual Contributor, Manager)  |
| Countries           | Filter by country (e.g., US, CA, FR)                     |
| Since               | Only return people with activity since this date         |
| Limit               | Maximum records to retrieve (default: 10, max: 250)      |

**Use cases:**

* **Contact discovery** – Find decision-makers at target accounts
* **Persona targeting** – Identify people by function and seniority
* **Regional targeting** – Find contacts in specific geographies

***

## Sumble data models

Cargo allows you to create data models from Sumble to trigger Plays and power model search actions.

### Fetch organizations

Pull organizations matching your technology criteria into Cargo.

**Configuration:**

| Filter                | Description                                  |
| --------------------- | -------------------------------------------- |
| Technologies          | Filter by technologies (e.g., python, react) |
| Technology categories | Filter by technology category                |
| Limit                 | Maximum number of records to retrieve        |

**Features:**

* Incremental sync (daily)
* Unifies accounts by organization ID

### Fetch jobs

Pull job postings matching your criteria into Cargo.

**Configuration:**

| Filter                | Description                              |
| --------------------- | ---------------------------------------- |
| Technologies          | Filter by technologies mentioned in jobs |
| Technology categories | Filter by technology category            |
| Countries             | Filter jobs by country                   |
| Limit                 | Maximum number of records to retrieve    |

**Features:**

* Incremental sync (daily)
* Tracks job postings by ID

***

## Credits

| Resource              | Cost                                                      |
| --------------------- | --------------------------------------------------------- |
| Organizations         | 5 credits per organization per filter (minimum 5 credits) |
| Technology enrichment | 5 credits per technology found                            |
| Jobs                  | 3 credits per job                                         |
| People                | 1 credit per person                                       |

***

## Best practices

* Use technology filters to find companies by their exact tech stack
* Combine organization search with people search for targeted outreach
* Monitor job postings for hiring intent and expansion signals
* Use enrichment to add technographic context to existing accounts
* Filter by recency to focus on actively growing organizations

<Info>
  For more information, visit the [Sumble API
  documentation](https://docs.sumble.com).
</Info>


# Surfe
Source: https://docs.getcargo.ai/integration/surfe

Connect Surfe to search and enrich people and companies in your workflows.

## How to set up Surfe

### Authentication

Surfe uses API key authentication:

1. Sign up at [surfe.com](https://surfe.com)
2. Generate an API key at [app.surfe.com/settings/api](https://app.surfe.com/settings/api)
3. Paste the API key in Cargo when connecting

<Note>
  **Code slugs** — integration slug: `surfe`. Actions: `searchPeople`, `searchCompanies`, `enrichPerson`, `findPersonByEmail`, `enrichCompany`. Call them as `integrations.surfe.<action>(...)`.
</Note>

Cargo spreads requests at up to 10 calls per second against the Surfe API.

## Surfe actions

### Search people

Search for people based on persona filters like job titles, seniority, departments, and company criteria.

**Optional fields:**

* **People filters**: Job titles (semantic matching, e.g. "CTO" matches "Chief Technology Officer"), Exact job titles, Seniorities, Departments, Countries, Countries excluded
* **Company filters**: Domains, Domains excluded, Company names, Industries, Industries excluded, Company countries, Employee count from/to, Keywords, Keywords excluded, Technologies, Technologies excluded
* **People per company**: Limits the number of people returned per company (1-5). Ignored if filters beyond domain/name are used
* **Limit**: Maximum number of results to return. Defaults to 10, max 200

**Use case:** Build lists of decision-makers matching your persona at target accounts.

### Search companies

Search for companies based on ICP filters like industry, employee count, revenue, technologies, and more.

**Optional fields:**

* **Company filters**: Domains, Domains excluded, Company names, Industries, Industries excluded, Countries, Employee count from/to, Revenue from/to, Keywords, Keywords excluded, Technologies, Technologies excluded, Year founded from/to, NAICS codes, NAICS codes excluded
* **Limit**: Maximum number of results to return. Defaults to 10, max 200

**Use case:** Source companies that match your ICP for list building and territory planning.

### Enrich person

Enrich a person with email, mobile phone, LinkedIn profile, and job history data. Provide at least a first name/last name or a LinkedIn URL.

**Optional fields:**

* **First name**: Person's first name
* **Last name**: Person's last name
* **Company name**: Name of the company the person works at
* **Company domain**: Domain of the company (e.g., surfe.com)
* **LinkedIn URL**: Person's LinkedIn profile URL
* **Include email**: Whether to include email in enrichment results (default: on)
* **Include mobile**: Whether to include mobile phone in enrichment results (default: on)
* **Include LinkedIn URL**: Whether to include LinkedIn URL in enrichment results (default: off)
* **Include job history**: Whether to include job history in enrichment results (default: off)

Enrichment runs asynchronously: Surfe processes the request and calls Cargo back via webhook (the run waits up to 120 minutes).

**Use case:** Get verified emails and mobile numbers for prospects in an enrichment waterfall.

### Find person by email

Search for a person given their email. Once the lookup completes, the result may include first name, last name, company name, company domain, job title, country, and LinkedIn URL.

**Required fields:**

* **Email**: The email address of the person to look up

Finding a LinkedIn URL costs 10 Surfe Search credits. Enrichment runs asynchronously via webhook, like Enrich person (the run waits up to 120 minutes).

**Use case:** Turn inbound signups or CRM emails back into LinkedIn profiles and job details.

### Enrich company

Enrich a company with firmographics data including address, employee count, revenue, industry, and more.

**Required fields:**

* **Company domain**: The company's domain (e.g., surfe.com). Must be a valid Fully Qualified Domain Name or Hostname

Enrichment runs asynchronously via webhook, like Enrich person (the run waits up to 120 minutes).

**Use case:** Enrich accounts with firmographics, funding rounds, and digital presence before scoring or routing.

## Best practices

* For person enrichment, a LinkedIn URL gives the most reliable match; otherwise provide first name + last name plus a company hint
* Only enable the enrichment data points you need (email, mobile, job history) — toggles map directly to what Surfe returns
* Combine **Search companies** → **Search people** → **Enrich person** to go from ICP to contactable leads in one workflow
* Use **Find person by email** when you already have an email and need the LinkedIn profile and job details back
* Enrichment actions are asynchronous — expect runs to stay in a waiting state until Surfe's webhook responds


# The Swarm
Source: https://docs.getcargo.ai/integration/the-swarm

Find warm introductions to target companies and people

The Swarm helps sales teams identify and leverage warm introductions to prospects. The Cargo integration enables you to find relationship paths between your company and target accounts or individuals.

## Authentication

Connect to The Swarm using your API key.

### Connection details

| Field       | Description            |
| ----------- | ---------------------- |
| **API Key** | Your The Swarm API key |

<Tip>
  Install The Swarm's Chrome extension for team members to improve relationship mapping over time.
</Tip>

***

## The Swarm actions

### Search warm intros to company

Find warm introductions to employees at a target company.

**Configuration**

| Field                     | Description                                |
| ------------------------- | ------------------------------------------ |
| **Your company domain**   | Domain of your company                     |
| **Target company domain** | Domain of the company you want to reach    |
| **Job functions**         | Filter by target employee job functions    |
| **Seniorities**           | Filter by target employee seniority levels |

<Info>
  Combine job functions and seniorities to find the right decision makers with warm paths.
</Info>

### Search warm intros to person

Find warm introductions to a specific individual.

**Configuration**

| Field                   | Description                           |
| ----------------------- | ------------------------------------- |
| **Your company domain** | Domain of your company                |
| **LinkedIn URL**        | LinkedIn profile of the target person |

***

## Credits

| Action                        | Cost                 |
| ----------------------------- | -------------------- |
| Search warm intros to company | 2 credits per search |
| Search warm intros to person  | 2 credits per search |

***

## Use cases

<AccordionGroup>
  <Accordion title="Account-based selling" icon="building">
    Find the best introduction paths to strategic accounts.
  </Accordion>

  <Accordion title="Warm outreach" icon="handshake">
    Prioritize leads based on relationship strength.
  </Accordion>

  <Accordion title="Relationship mapping" icon="sitemap">
    Understand your team's network connections to target companies.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Install the Chrome extension** - Team-wide adoption improves relationship data quality
2. **Filter by seniority** - Focus on decision makers with the right seniority level
3. **Use with enrichment** - Combine with contact enrichment to build complete prospect profiles


# TheirStack
Source: https://docs.getcargo.ai/integration/their-stack

Connect TheirStack to discover companies and job postings by technology stack in your workflows.

## How to set up TheirStack

### Authentication

TheirStack uses API key authentication:

1. Sign up at [theirstack.com](https://theirstack.com)
2. Navigate to your API settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## TheirStack actions

### Search companies

Find companies based on hiring signals and technology usage.

**Company filters:**

| Filter              | Description                          |
| ------------------- | ------------------------------------ |
| Revenue             | Revenue range in USD                 |
| Employee count      | Number of employees                  |
| Company type        | Type of company                      |
| Industries          | LinkedIn industry codes              |
| YC companies only   | Filter to Y Combinator companies     |
| Company name/domain | Exact or partial matching            |
| LinkedIn URL        | Company LinkedIn page                |
| Description pattern | Regex search in company descriptions |
| Country/location    | Geographic filters                   |
| Technologies        | Tech stack filters (OR/AND/NOT)      |
| Funding             | Funding amount and stage             |
| Investors           | Filter by investors                  |

**Job filters (for companies with matching jobs):**

| Filter           | Description                      |
| ---------------- | -------------------------------- |
| Job title        | Title patterns (regex supported) |
| Job seniority    | Level filters                    |
| Job description  | Content matching                 |
| Job location     | Geographic filters               |
| Remote           | Remote job filter                |
| Job technologies | Tech mentioned in job postings   |
| Salary range     | Compensation filters             |
| Posted date      | Job posting date range           |

**Use case:** Find companies actively hiring for specific technologies.

### Search jobs

Find job postings with detailed filtering.

**Job filters:** Same as company search job filters.

**Company filters:** Same as company search company filters.

**Credits:** 0.5 credits per result

**Use case:** Discover companies hiring for specific roles and technologies.

### Search technologies

Find companies by their technology usage patterns.

**Technology filters:**

| Filter                | Description                  |
| --------------------- | ---------------------------- |
| Technology slug       | Specific technologies        |
| Technology category   | Technology categories        |
| Parent category       | High-level technology groups |
| Confidence            | High/medium/low confidence   |
| Max rank              | Technology importance rank   |
| Relative occurrence   | Usage frequency              |
| Min/max jobs          | Job count with technology    |
| First/last date found | Discovery timeline           |

**Credits:** 0.5 credits (fixed)

**Use case:** Find companies adopting or using specific technologies.

## TheirStack data models

### Fetch companies

Pull companies matching your criteria into Cargo.

**Configuration:** Same as search companies.

**Features:**

* Incremental sync (daily)
* Unifies accounts by domain and LinkedIn
* 0.5 credits per result

### Fetch jobs

Pull job postings into Cargo.

**Configuration:** Same as search jobs.

**Features:**

* Incremental sync (daily)
* 0.5 credits per result

## Credits

| Action              | Credits        |
| ------------------- | -------------- |
| Search companies    | Per result     |
| Search jobs         | 0.5 per result |
| Search technologies | 0.5 (fixed)    |
| Fetch companies     | 0.5 per result |
| Fetch jobs          | 0.5 per result |

## Rate limits

TheirStack API has a rate limit of 4 requests per second. Cargo handles rate limiting automatically.

## Best practices

* Use technology filters to find companies by their tech stack
* Combine job and company filters for precise targeting
* Use job posting recency for hiring intent signals
* Filter by funding stage for growth-stage companies
* Leverage description patterns for niche use cases


# Theneo
Source: https://docs.getcargo.ai/integration/theneo

Verify email addresses with Theneo

Theneo provides email verification services to validate email addresses for deliverability.

## Authentication

Connect to Theneo using your API key.

### Connection details

| Field       | Description         |
| ----------- | ------------------- |
| **API key** | Your Theneo API key |

***

## Theneo actions

### Verify email

Validate an email address to check if it's deliverable.

**Configuration**

| Field     | Description             |
| --------- | ----------------------- |
| **Email** | Email address to verify |

**Returns**

| Field          | Description                      |
| -------------- | -------------------------------- |
| Validity       | Whether the email is valid       |
| Deliverability | Whether the email is deliverable |
| Risk level     | Risk assessment of the email     |

***

## Use cases

<AccordionGroup>
  <Accordion title="List cleaning" icon="broom">
    Verify email lists before outreach campaigns.
  </Accordion>

  <Accordion title="Lead validation" icon="check-circle">
    Validate emails at point of capture.
  </Accordion>

  <Accordion title="Deliverability optimization" icon="envelope-circle-check">
    Improve sender reputation by removing invalid emails.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Verify before campaigns** - Always verify emails before adding to sequences
2. **Handle invalid emails** - Remove or flag invalid email addresses
3. **Cache results** - Verification results are cached to reduce costs


# Waterfall.io
Source: https://docs.getcargo.ai/integration/waterfall

Enrich contacts and find prospects with Waterfall.io

Waterfall.io is a B2B data enrichment platform that provides contact and company information, phone numbers, and email verification. The Cargo integration enables comprehensive prospecting and enrichment workflows.

## Authentication

Connect to Waterfall.io using your API key.

### Connection details

| Field       | Description               |
| ----------- | ------------------------- |
| **API Key** | Your Waterfall.io API key |

***

## Waterfall.io actions

### Enrich company

Retrieve detailed company information.

**Configuration**

| Field        | Description                   |
| ------------ | ----------------------------- |
| **LinkedIn** | Company LinkedIn URL or slug  |
| **Domain**   | Company domain or website URL |
| **Name**     | Company name                  |

### Enrich contact

Retrieve contact information including email and profile data.

**Configuration**

| Field                    | Description                       |
| ------------------------ | --------------------------------- |
| **LinkedIn**             | Contact LinkedIn URL or slug      |
| **Full name**            | Full name of the contact          |
| **First name**           | First name of the contact         |
| **Last name**            | Last name of the contact          |
| **Domain**               | Company domain                    |
| **Email**                | Professional or personal email    |
| **Include extra fields** | Include additional profile fields |

### Find phone

Retrieve a contact's phone number.

**Configuration**

Same fields as Enrich contact, focused on phone number retrieval.

### Search prospects

Search for contacts at a company with filtering options.

**Configuration**

| Field                | Description                      |
| -------------------- | -------------------------------- |
| **Company domain**   | Domain of the company (required) |
| **Company name**     | Company name                     |
| **LinkedIn**         | Company LinkedIn handle          |
| **Title filter**     | Filter by job title              |
| **Title filters**    | Multiple title filters           |
| **Location country** | Contact's country                |
| **Location name**    | Contact's city/region            |
| **Excluded names**   | Names to exclude from results    |
| **Limit**            | Maximum number of results        |

### Verify email

Verify if an email address is valid and deliverable.

**Configuration**

| Field     | Description             |
| --------- | ----------------------- |
| **Email** | Email address to verify |

### Detect job change

Detect if a contact has changed jobs. Returns the job change status (MOVED, LEFT, NO\_CHANGE, UNKNOWN) and updated person information.

**Configuration**

| Field                  | Description                                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Professional email** | Work email address of the contact. Required for most lookups unless personal email or contact LinkedIn is provided. |
| **Personal email**     | Personal email address of the contact. Used as an alternative to professional email.                                |
| **Company domain**     | Domain of the company (e.g., deel.com). Helps improve matching accuracy.                                            |
| **Company LinkedIn**   | LinkedIn URL of the company (e.g., linkedin.com/company/digital-river).                                             |
| **Contact LinkedIn**   | LinkedIn profile URL of the contact. This input yields the highest coverage when combined with company domain.      |

***

## Credits

| Action            | Cost                 |
| ----------------- | -------------------- |
| Enrich company    | 1 credit             |
| Enrich contact    | 2 credits            |
| Find phone        | 7 credits            |
| Search prospects  | 3 credits per result |
| Verify email      | 0.1 credits          |
| Detect job change | 3 credits            |

***

## Use cases

<AccordionGroup>
  <Accordion title="Contact enrichment" icon="user-plus">
    Enrich leads with email, phone, and profile data.
  </Accordion>

  <Accordion title="Prospecting" icon="magnifying-glass">
    Find contacts at target companies by title and location.
  </Accordion>

  <Accordion title="Phone outreach" icon="phone">
    Get direct dial phone numbers for sales outreach.
  </Accordion>

  <Accordion title="Email verification" icon="envelope-circle-check">
    Verify emails before adding to campaigns.
  </Accordion>

  <Accordion title="Job change detection" icon="briefcase">
    Detect when contacts change jobs to re-engage churned champions or identify
    new opportunities.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Provide multiple identifiers** - LinkedIn + domain improves match rates
2. **Use title filters** - Target specific roles with title filter syntax
3. **Verify before sending** - Use email verification to protect deliverability


# Wiza
Source: https://docs.getcargo.ai/integration/wiza

Connect Wiza to enrich contact profiles with emails and phone numbers in your workflows.

## How to set up Wiza

### Authentication

Wiza uses API key authentication:

1. Sign up at [wiza.co](https://wiza.co)
2. Navigate to your API settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## Wiza actions

### Enrich person

Get comprehensive contact information including emails and phone numbers.

**Input fields (provide as many as available):**

* **Full name**: Person's full name
* **Company**: Company name
* **Domain**: Company domain
* **Profile URL**: LinkedIn profile URL
* **Email**: Known email address

**Data type options:**

* **Work email**: Professional email address
* **Personal email**: Personal email address
* **Phone**: Phone number

**Use case:** Enrich contact profiles with verified email and phone data.

## Response data

Wiza enrichment returns:

| Field           | Description          |
| --------------- | -------------------- |
| full\_name      | Person's full name   |
| first\_name     | First name           |
| last\_name      | Last name            |
| title           | Job title            |
| company         | Company name         |
| work\_email     | Professional email   |
| personal\_email | Personal email       |
| phone           | Phone number         |
| linkedin\_url   | LinkedIn profile URL |

## Retry behavior

Wiza actions include automatic retry logic:

* Maximum 11 retry attempts
* Exponential backoff (starting at 2 seconds)
* Handles rate limits automatically

## Best practices

* Provide LinkedIn URL for most reliable matching
* Include company domain when available
* Select only the data types you need
* Use caching to avoid redundant enrichment
* Combine with verification for highest data quality


# ZeroBounce
Source: https://docs.getcargo.ai/integration/zero-bounce

Connect ZeroBounce to verify email addresses and improve deliverability in your workflows.

## How to set up ZeroBounce

### Authentication

ZeroBounce uses API key authentication:

1. Sign up at [zerobounce.com](https://zerobounce.com)
2. Navigate to your API settings
3. Copy your API key
4. Paste the API key in Cargo when connecting

## ZeroBounce actions

### Verify email

Check if an email address is valid and deliverable.

**Required fields:**

* **Email**: The email address to verify

**Credits:** 0.1 credits per verification

## Verification statuses

ZeroBounce returns detailed verification results:

| Status        | Description                              |
| ------------- | ---------------------------------------- |
| valid         | Email exists and is deliverable          |
| invalid       | Email does not exist or will bounce      |
| catch-all     | Domain accepts all emails (unverifiable) |
| spamtrap      | Known spam trap - do not email           |
| abuse         | Known complainer address                 |
| do\_not\_mail | Should not be emailed (role-based, etc.) |
| unknown       | Unable to determine status               |

## Response data

| Field          | Description                    |
| -------------- | ------------------------------ |
| status         | Verification status            |
| sub\_status    | Detailed status reason         |
| account        | Email account name             |
| domain         | Email domain                   |
| did\_you\_mean | Suggested correction for typos |
| domain\_age    | Age of the domain              |
| free\_email    | Is it a free email provider?   |
| mx\_found      | Does domain have MX records?   |
| mx\_record     | Primary MX record              |
| smtp\_provider | Email service provider         |

## Best practices

* Verify emails before importing to your email platform
* Re-verify old contacts periodically (emails decay)
* Treat "catch-all" as valid but monitor bounces
* Never email "spamtrap" or "abuse" addresses
* Use "did\_you\_mean" to suggest corrections
* Cache verification results to save credits

## Integration with other tools

ZeroBounce works well in combination with:

* **Email finders**: Verify found emails before outreach
* **CRM sync**: Keep verification status updated
* **Campaign tools**: Ensure list hygiene before sends


# ZoomInfo
Source: https://docs.getcargo.ai/integration/zoominfo

Access B2B contact and company data with ZoomInfo

ZoomInfo is a leading B2B data platform providing company and contact information for sales and marketing teams. The Cargo integration enables you to enrich records, search for companies and contacts, and access intent data.

## Authentication

ZoomInfo supports two authentication methods.

### Username and password

| Field        | Description            |
| ------------ | ---------------------- |
| **Username** | Your ZoomInfo username |
| **Password** | Your ZoomInfo password |

### Public Key Infrastructure (PKI)

| Field           | Description            |
| --------------- | ---------------------- |
| **Username**    | Your ZoomInfo username |
| **Client ID**   | Your PKI client ID     |
| **Private key** | Your PKI private key   |

***

## ZoomInfo actions

### Enrich company

Retrieve detailed information about a company.

**Configuration**

| Field               | Description                  |
| ------------------- | ---------------------------- |
| **Company ID**      | ZoomInfo company ID          |
| **Company name**    | Company name                 |
| **Company website** | Company website URL          |
| **Company ticker**  | Stock ticker symbol          |
| **Company phone**   | Company phone number         |
| **IP address**      | Company IP address           |
| **Address fields**  | Street, city, state, country |

### Enrich contact

Retrieve detailed information about a contact.

**Configuration**

| Field             | Description            |
| ----------------- | ---------------------- |
| **Person ID**     | ZoomInfo person ID     |
| **Full name**     | Contact's full name    |
| **First name**    | Contact's first name   |
| **Last name**     | Contact's last name    |
| **Email address** | Contact's email        |
| **Phone**         | Contact's phone number |
| **Job title**     | Contact's job title    |
| **Company name**  | Contact's company      |

### Search companies

Search for companies matching specific criteria.

**Configuration**

| Field                | Description                    |
| -------------------- | ------------------------------ |
| **Company type**     | Private, public, etc.          |
| **Industry codes**   | Industry classification codes  |
| **Revenue range**    | Annual revenue range           |
| **Employee count**   | Employee count range           |
| **Location filters** | Country, state, metro region   |
| **Tech stack**       | Technology products used       |
| **Funding filters**  | Funding amount and date ranges |
| **Growth metrics**   | Employee growth rate filters   |
| **Enrich**           | Return full company details    |
| **Limit**            | Maximum records to retrieve    |

### Search contacts

Search for contacts matching specific criteria.

**Configuration**

| Field                | Description                    |
| -------------------- | ------------------------------ |
| **Job title**        | Contact's job title            |
| **Management level** | C-level, VP, Director, etc.    |
| **Department**       | Sales, Marketing, Engineering  |
| **Job function**     | Specific job function          |
| **Company filters**  | Company name, size, industry   |
| **Location filters** | Country, state, metro region   |
| **Accuracy score**   | Minimum contact accuracy score |
| **Enrich**           | Return full contact details    |
| **Limit**            | Maximum records to retrieve    |

### Search intents

Search for buyer intent signals.

**Configuration**

| Field                 | Description                 |
| --------------------- | --------------------------- |
| **Topics**            | Intent topics to search     |
| **Signal date range** | Start and end dates         |
| **Signal score**      | Minimum and maximum scores  |
| **Audience strength** | Audience strength range     |
| **Limit**             | Maximum records to retrieve |

### Search news

Search for company news and updates.

**Configuration**

| Field          | Description                 |
| -------------- | --------------------------- |
| **Categories** | News categories             |
| **URL**        | Specific URL to search      |
| **Date range** | Page date min/max           |
| **Limit**      | Maximum records to retrieve |

### Search scoops

Search for company "scoops" (verified buying signals).

**Configuration**

| Field               | Description                 |
| ------------------- | --------------------------- |
| **Scoop type**      | Type of scoop               |
| **Scoop topic**     | Topic of the scoop          |
| **Company filters** | Company name, ID, website   |
| **Location**        | Geographic filters          |
| **Published date**  | Publication date range      |
| **Limit**           | Maximum records to retrieve |

***

## Use cases

<AccordionGroup>
  <Accordion title="Lead enrichment" icon="database">
    Enrich leads with verified contact information and company data.
  </Accordion>

  <Accordion title="List building" icon="list">
    Build targeted prospect lists based on firmographic and demographic criteria.
  </Accordion>

  <Accordion title="Intent-based outreach" icon="bullseye">
    Identify companies showing buying intent for timely outreach.
  </Accordion>

  <Accordion title="Account research" icon="magnifying-glass">
    Research accounts with news, scoops, and company insights.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Use accuracy scores** - Filter contacts by accuracy score for better deliverability
2. **Combine filters** - Use multiple criteria to build highly targeted lists
3. **Leverage intent data** - Prioritize outreach to companies showing buying intent
4. **Monitor API usage** - ZoomInfo has usage limits based on your subscription


# Overview
Source: https://docs.getcargo.ai/mailboxes/overview

Owned sending domains and mailboxes for outbound email. Register a domain with defineDomain, provision mailboxes with defineMailbox, and send from plays and tools with sendEmail.

A **mailbox** is an inbox Cargo owns and sends from — `jane@acme-outreach.com`, not a connected Gmail or Outlook account. Mailboxes live on a **sending domain** you register through Cargo. You send from them with the native `sendEmail` action, the same way a play calls `allocate` or a connector action.

There is no HTTP "send" route. Delivery is a native action so workflows reuse orchestration's pacing, retries, and credit charge. Direct delivery would skip all three.

## How the pieces fit

```mermaid theme={null}
flowchart LR
  D["defineDomain"] --> M["defineMailbox"]
  M --> W["Warm-up"]
  W --> S["sendEmail in a play or tool"]
  S --> T["Thread + events"]
```

1. **Register a domain** with [`defineDomain`](#register-a-sending-domain) (or buy one in the UI).
2. **Declare mailboxes** on that domain with [`defineMailbox`](#declare-a-mailbox). Google, shared, or private inboxes.
3. **Start warm-up** so the daily send ceiling can climb from 5 to 40 over 45 days.
4. **Send** from a [play](/plays/overview) or [tool](/tools/overview) with `sendEmail({ mailboxUuid: jane.uuid, … })`. Orchestration spaces those sends across the day and refuses once the rolling 24-hour allowance is spent.
5. **Watch the thread** — opens, clicks, replies, and unsubscribes land as events on the conversation.

See [Sending](/mailboxes/sending) for pacing, warm-up, and the `sendEmail()` helper, and [Using the UI](/mailboxes/using-ui) for the same flow in the app.

## Register a sending domain

A mailbox can only be created on a domain the workspace already owns and that is **active**. `defineDomain` is the declarative resource for that:

```ts domains/outreach.ts theme={null}
import { defineDomain } from "@cargo-ai/cdk";

// Bind a domain already bought in the Cargo UI. destroy then releases it
// rather than cancelling a registration the deploy never paid for.
export const outreach = defineDomain("acme-outreach.com", { adopt: true });
```

Omit `adopt` to **register** a new domain through Cargo. Registration charges workspace credits and is not refundable — a `+ create domain:…` line in `cargo-ai project plan` is the signal, and the deploy confirmation is where it's approved.

```ts theme={null}
export const outreach = defineDomain("acme-outreach.com", {
  dnsRecords: [
    { type: "MX", name: "@", value: "mail.mailpool.io", priority: 10 },
    { type: "TXT", name: "@", value: "v=spf1 include:mailpool.io ~all" },
  ],
});
```

<Warning>
  `dnsRecords` is the **whole zone**, not a patch. Declaring it replaces every
  live record, including the ones the registrar wrote at purchase. Leave it off
  to manage only the domain's lifecycle and let the zone be edited elsewhere.
  `[]` empties the zone.
</Warning>

A freshly registered domain sits at `pending` while the registrar provisions it. The deploy waits until it is `active` before publishing DNS or creating mailboxes.

The domain is addressed by its name, the way a member is addressed by email. If the workspace already owns that name and the spec does not say `adopt: true`, deploy fails with the way out (`cargo-ai project import` or `adopt: true`) rather than buying it a second time.

## Declare a mailbox

`defineMailbox` provisions an inbox on that domain. Pass the domain handle — the deploy waits until the domain is active, then creates the mailbox and moves on. The mailbox itself may still be `pending`; it becomes `active` once the provider has issued credentials. A `sendEmail` before then fails with `credentialsMissing`.

```ts mailboxes/jane.ts theme={null}
import { defineMailbox } from "@cargo-ai/cdk";

import { outreach } from "../domains/outreach";

export const jane = defineMailbox("jane", {
  domain: outreach,
  type: "google",
  firstName: "Jane",
  lastName: "Doe",
});
```

That yields `jane@acme-outreach.com`. The slug is the project identity (`mailbox:jane`); `username` defaults to the slug. When two inboxes share a local part on different domains, pick a unique slug and set `username` explicitly:

```ts theme={null}
export const janeSales = defineMailbox("jane_sales", {
  domain: sales,
  type: "google",
  username: "jane",
  firstName: "Jane",
  lastName: "Doe",
});
```

`jane.uuid` is a deferred token. Pass it to `sendEmail` the same way you pass a capacity handle to `allocate`:

```ts theme={null}
sendEmail({
  mailboxUuid: jane.uuid,
  to: input.email,
  subject: "Quick note",
  bodyHtml: "<p>Hi</p>",
});
```

| Field                    | Meaning                                                                                                   |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| `domain`                 | A `defineDomain` handle or `domainRef("uuid")`. Must be **active** before the mailbox is created.         |
| `type`                   | `google`, `shared`, or `private` (SMTP). `outlook` cannot be provisioned — Graph delivery has not landed. |
| `username`               | Local part of the address. Defaults to the slug. Letters, digits, dots, dashes, underscores.              |
| `firstName` / `lastName` | Used as the From display name. Reconciled on every deploy.                                                |
| `signature`              | Optional HTML stored on the mailbox. Omit to leave whatever is live; declare it to set it.                |
| `folder`                 | Optional [folder](/folders/overview) of kind `mailbox`.                                                   |
| `adopt`                  | Bind an inbox the workspace already owns at `username@domain` instead of provisioning a new one.          |

The workspace must have credits on file. Creating a mailbox charges a **monthly** fee in credits for as long as it exists (Google 125, shared and private 100). A send then charges **0.1 credits** per delivered email. `destroy` deletes a mailbox the project created (and stops the fee); an adopted mailbox is released, never deleted.

Provisioning is asynchronous. A new mailbox starts `pending` and becomes `active` once the provider has issued credentials. The deploy does not wait for that — unlike a domain registration, which must be `active` before DNS or mailboxes can be written. Only an `active` mailbox can send. Auth failure or a spam flag from the provider moves it to `inactive` and sending stops immediately.

Domain, username, and type are create-only. Changing them is a destroy plus a new `defineMailbox`. If the workspace already owns that address and the spec does not say `adopt: true`, deploy fails with the way out rather than provisioning a second inbox.

A mailbox created in the UI (or by an earlier deploy whose state file was lost) is bound the same way as a domain:

```ts theme={null}
export const jane = defineMailbox("jane", {
  domain: outreach,
  type: "google",
  firstName: "Jane",
  lastName: "Doe",
  adopt: true,
});
```

## Organize with folders

Mailbox folders are a separate namespace from model or agent folders. Declare one with `defineFolder` and pass the handle:

```ts folders/outreach.ts theme={null}
import { defineFolder, defineMailbox } from "@cargo-ai/cdk";

import { outreach } from "../domains/outreach";

export const mailboxFolder = defineFolder("outreach-mailboxes", {
  kind: "mailbox",
  name: "Outreach",
});

export const jane = defineMailbox("jane", {
  domain: outreach,
  type: "google",
  firstName: "Jane",
  lastName: "Doe",
  folder: mailboxFolder,
});
```

## What a mailbox is not

Cargo mailboxes are not a replacement for [Resend](/integration/resend), [SendGrid](/integration/sendgrid), or [Lemlist](/integration/lemlist). Those remain connector actions against *your* ESP or sequencer. A Cargo mailbox is an inbox the workspace owns, warmed and paced so cold outreach from a new domain does not burn the domain's reputation.

## From the CLI

Prefer `defineMailbox` for the inbox itself. Use the CLI for warm-up, allowance, threads, events, and suppressions — the same surface as the [mailbox management API](/api-reference/introduction).

```bash theme={null}
cargo-ai mailboxManagement mailbox list
cargo-ai mailboxManagement mailbox get 550e8400-e29b-41d4-a716-446655440000
cargo-ai mailboxManagement mailbox get-send-allowance 550e8400-e29b-41d4-a716-446655440000
cargo-ai mailboxManagement mailbox start-warmup 550e8400-e29b-41d4-a716-446655440000
cargo-ai mailboxManagement thread list --mailbox-uuid 550e8400-e29b-41d4-a716-446655440000
cargo-ai mailboxManagement suppression create --email opted-out@acme.com
```

Ad-hoc sends still go through orchestration, so they pick up the same rate limit and credit charge as a play:

```bash theme={null}
cargo-ai orchestration action execute \
  --action '{"kind":"native","actionSlug":"sendEmail","config":{}}' \
  --data '{"mailboxUuid":"<uuid>","to":"lead@acme.com","subject":"Hello","bodyHtml":"<p>Hi</p>"}' \
  --wait-until-finished
```


# Sending
Source: https://docs.getcargo.ai/mailboxes/sending

sendEmail() in a play or tool, waitEmailEvent() after a send, the warm-up ramp, and the per-mailbox rate limit that spaces sends across the day.

Sending is the native `sendEmail` action. In a [workflow](/workflows/overview) body you call it the same way as `allocate` or `delay` — destructure `sendEmail` from the scope and pass the mailbox uuid, recipient, subject, and body.

## Send from a play

```ts plays/outreach.ts theme={null}
import { definePlay, defineWorkflow } from "@cargo-ai/cdk";
import { z } from "zod";

import { jane } from "../mailboxes/jane";
import { contacts } from "../models/contacts";

const sendIntro = defineWorkflow(
  "send-intro",
  {
    input: z.object({ email: z.string(), firstName: z.string() }),
    output: z.object({ messageUuid: z.string().optional() }),
  },
  ({ input, sendEmail }) => {
    const sent = sendEmail({
      mailboxUuid: jane.uuid,
      to: input.email,
      subject: `Quick note, ${input.firstName}`,
      bodyHtml: `<p>Hi ${input.firstName},</p><p>Worth a conversation?</p>`,
    });
    return { messageUuid: sent.messageUuid };
  },
);

export const outreach = definePlay("outreach", {
  model: contacts,
  workflow: sendIntro,
  changeKinds: ["added"],
  schedule: { type: "realtime" },
});
```

`mailboxUuid` is the mailbox handle's `uuid` token, not the domain and not the address. A mailbox you did not declare in this repo can still be referenced with a literal uuid (or `mailboxRef("uuid").uuid`).

| Field         | Required | Meaning                                                                                                                           |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `mailboxUuid` | yes      | Mailbox to send from. Must be `active` and have credentials.                                                                      |
| `to`          | yes      | Recipient. Normalised to lowercase; checked against the workspace suppression list before anything else.                          |
| `subject`     | yes      | Subject line.                                                                                                                     |
| `bodyHtml`    | no       | HTML body. Open/click tracking and a `List-Unsubscribe` link are baked into the MIME that is delivered, not into the stored copy. |
| `bodyText`    | no       | Plain-text fallback. Generated from the HTML when omitted.                                                                        |
| `inReplyTo`   | no       | `Message-ID` this message replies to.                                                                                             |
| `references`  | no       | Full ancestry chain, oldest first, so the reply stays threaded past the first exchange.                                           |

The node returns `messageUuid`, `rfcMessageId`, `providerMessageId`, and `sentAt`. Each delivered email costs **0.1 credits**.

A suppressed recipient, a missing or inactive mailbox, or missing credentials fail without retry — those need a human. A daily cap or a transport error **does** retry, because the cap lifts on its own and the transport can recover.

<Note>
  `sendEmail` is deliberately not serialized behind a lock. When a workflow has
  both a lock and a rate limit, the lock wins and the rate limit is skipped —
  which would unpace every send from that mailbox.
</Note>

An [agent](/agents/overview) does not call `sendEmail` directly. Wrap it in a tool and put that tool in the agent's `uses`.

## Wait for a reply, view, or unsubscribe

`waitEmailEvent` pauses the run until a mailbox event lands on the **thread** of a sent email. Point it at the `messageUuid` `sendEmail` just returned — the wait loads that message and matches events on any send in the same conversation. If `timeoutHours` elapses first (default 72, cap 720), the node **fails** the run.

```ts theme={null}
({ input, sendEmail, waitEmailEvent }) => {
  const sent = sendEmail({
    mailboxUuid: jane.uuid,
    to: input.email,
    subject: `Quick note, ${input.firstName}`,
    bodyHtml: `<p>Hi ${input.firstName},</p>`,
  });

  waitEmailEvent({
    messageUuid: sent.messageUuid,
    kind: "replied",
    timeoutHours: 72,
  });
};
```

| `kind`         | Completes on                                     |
| -------------- | ------------------------------------------------ |
| `replied`      | An inbound reply on the thread                   |
| `opened`       | A tracking-pixel view (shown as **When viewed**) |
| `unsubscribed` | An unsubscribe                                   |
| `interacted`   | A view, click, or reply — not an unsubscribe     |

If the activity already happened, the node completes immediately — it does not wait.

## Warm-up and the daily ceiling

Two different "warm-ups" sit on the same mailbox, and only one of them moves the send cap.

| What                 | What it does                                                                         | How you see it                                                        |
| -------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| **Provider warm-up** | Mailpool sends dummy mail into a warm-up pool to build the inbox's reputation.       | Mailbox page → Warm-up card: off / pending / active / paused / failed |
| **Cargo send ramp**  | Caps *your* real outreach. Computed from `warmupStartedAt`, not stored as a counter. | Mailbox page → **Send allowance**: daily limit / sent / left          |

Starting provider warm-up sets `warmupStartedAt` and the ramp begins. Until then — warm-up off, never started, or stopped — the mailbox stays at the **floor of 5 real sends per rolling 24 hours**, even if it is months old. Stopping warm-up clears the timestamp and the ramp starts again from 5 the next time you start it.

The ceiling itself is a formula evaluated whenever allowance is read (the mailbox page, `sendEmail` pacing, and the send backstop):

```
elapsedDays = floor((now − warmupStartedAt) / 24h)

if warmupStartedAt is null → 5
if elapsedDays ≥ 45      → 40
else                     → floor(5 + (40 − 5) × elapsedDays / 45)
```

So day 0–1 is 5, day 2 is 6, day 22 (halfway) is 22, day 45+ is 40. An optional per-mailbox `dailySendLimit` can only **tighten** that, never raise it — a mailbox created this morning cannot send 500 by setting an override.

The 45-day shape matches Mailpool's default warm-up schedule so Cargo's own pacing and the provider's dummy traffic ramp together rather than fighting each other. 40/day is deliberately below the 50/day figure cold-outreach playbooks quote: the fleet scales by adding mailboxes, not by pushing any single one to its limit.

## How the number updates

Nothing writes `6`, then `7`, into a column as days pass. Each read of send allowance does two things:

1. **`dailyLimit`** — the formula above, right now.
2. **`sentCount`** — successful deliveries in the **last 24 hours** (rolling, not midnight). Pending and error rows do not count. `remainingCount` is `dailyLimit − sentCount`.

A successful send adds a `success` message row. The next allowance read counts it, **Left** drops by one, and the spacing stays `24h / dailyLimit`. When that send ages out of the window, **Left** comes back. A mailbox that emptied its quota at 23:00 does not get a fresh burst at midnight — that burst is what providers penalise.

`warmupDailyTarget` on the mailbox is Mailpool's dummy-mail target. It is **not** the real-send cap.

## Per-mailbox rate limit

Before each `sendEmail` node runs, orchestration asks the action for a rate limit. The policy is **spread**, keyed **per mailbox** (`mailboxManagement:mailboxes:<uuid>`), so two workflows targeting the same inbox serialize and unrelated mailboxes do not queue behind each other.

Spread turns "N per day" into **one send every `24h / N`**:

| Daily limit       | Spacing     |
| ----------------- | ----------- |
| 5 (never warmed)  | \~4.8 hours |
| 40 (fully warmed) | 36 minutes  |

Spacing is sized from the **daily ceiling**, not from what is left. Sizing it on the remainder would stretch as the day burned down (36 minutes at 40 left → 24 hours at one left) and the mailbox would never spend the allowance the ramp granted it.

Idle time does not accrue credit. A backlog after a quiet period is still admitted one slot at a time, not dumped all at once.

The limiter will not park a run longer than **remaining slots × spacing**. A mailbox with 40 left and 36-minute spacing admits at most \~40 waiting sends (about 24 hours). The 41st fails immediately with `rateLimitWaitTooLong` instead of sleeping for two days. When **Left** is already 0, a wait of 0ms still reaches the send backstop (`dailyLimitReached`, which retries); any positive wait is refused.

If the allowance cannot be read, the throttle **fails closed** to one send per day rather than running unthrottled, and still refuses to queue. A misconfigured node with no mailbox uuid shares a workspace-wide slot.

Even after a slot is admitted, delivery re-checks remaining count. If it is 0, the node returns `dailyLimitReached` and retries later.

### Why a send-email span stays pending

A span is created as `pending` as soon as the run reaches the node. The workflow then **sleeps before it executes** the send, waiting for the next slot on that mailbox. For a never-warmed inbox that is up to \~4.8 hours, and never more than today's remaining allowance.

That is the pacer, not a hung worker. Nothing has been delivered yet. Other mailboxes are unaffected. If the wait would exceed remaining capacity, the node errors with `rateLimitWaitTooLong` instead of staying pending.

## Threads, tracking, and suppressions

Each send is filed into a **thread** — a new uuid when the message starts a conversation, otherwise the parent matched via `In-Reply-To` / `References`. Replies pulled from IMAP become events on that thread rather than new message rows. The workspace **Emails** view and the mailbox **Emails** tab are thread lists.

Events are the reporting surface, in roughly the order they can happen:

| Kind                 | Source                                                     |
| -------------------- | ---------------------------------------------------------- |
| `sent`               | Cargo's own record of delivery                             |
| `opened` / `clicked` | Tracking URLs baked into the MIME                          |
| `replied`            | IMAP poll of INBOX (and Junk)                              |
| `unsubscribed`       | `List-Unsubscribe` link in the message                     |
| `bounced`            | Reserved; nothing parses delivery status notifications yet |

The daily ramp counts **successful message rows**, not `sent` events, so a dropped event can never widen a mailbox's allowance.

**Suppression** is workspace-wide. A recipient who unsubscribes, bounces, or is added manually is opted out of *the sender*, not of one address the sender happens to own. A suppressed `to` is refused before a row is written.

## One-off send

To send without a play, execute the same native action. Inputs go in `--data`; `action.config` stays empty:

```bash theme={null}
cargo-ai orchestration action execute \
  --action '{"kind":"native","actionSlug":"sendEmail","config":{}}' \
  --data '{"mailboxUuid":"<uuid>","to":"lead@acme.com","subject":"Hello","bodyHtml":"<p>Hi</p>"}' \
  --wait-until-finished
```

Dry runs of a play or tool do not deliver and do not consume the allowance.


# Using the UI
Source: https://docs.getcargo.ai/mailboxes/using-ui

Register a sending domain, provision mailboxes, start warm-up, and add a Send email node to a play — no code required.

Everything on [Overview](/mailboxes/overview) and [Sending](/mailboxes/sending) can be done from the workspace. This page walks through that end-to-end.

## What you'll build

A sending domain, one mailbox on it, warm-up running, and a play that sends from that mailbox as new contacts land.

***

## Step-by-step

### Step 1: Register a domain

1. Open **Settings → Domains**
2. Buy a sending domain, or bind one the workspace already owns
3. Wait until its status is **active** — a new registration sits at pending while the registrar provisions it
4. Confirm MX and SPF are in place if you are not letting Cargo publish the zone

A mailbox can only be created on an active domain the workspace owns. The same domain is what [`defineDomain`](/mailboxes/overview#register-a-sending-domain) manages from code, and the same mailbox is what [`defineMailbox`](/mailboxes/overview#declare-a-mailbox) declares. The create-mailbox form only lists **active** domains.

### Step 2: Create a mailbox

1. Open **Send → Mailboxes** and click **New mailbox**
2. Pick the domain, a type (**Google**, **shared**, or **private**), and the local part of the address
3. Fill in first and last name (the From display name) and an optional signature
4. Optionally file it in a mailbox folder

The mailbox starts **pending**. The overview page polls until the provider has issued credentials and the status becomes **active**. Only then can it send. Auth failure or a spam flag later moves it to **inactive** and sending stops.

Monthly credits start being charged once the mailbox exists. See [Overview](/mailboxes/overview#provision-a-mailbox) for the rates.

### Step 3: Start warm-up

On the mailbox **Overview**:

1. The **Warm-up** card reads "Warm-up is off" until you start it
2. Click **Start** — that both turns on Mailpool's dummy-mail pool *and* starts Cargo's 45-day send ramp
3. Pause / resume from the same card; **Stop** tears the pool down and resets the ramp to 5/day

Until warm-up has been started, **Send allowance → Daily limit** stays at **5**, even if the mailbox is months old. That is the never-warmed floor, not "unlimited because warm-up is off".

### Step 4: Read send allowance

The **Send allowance** card is what the pacer actually uses:

* **Daily limit** — the ramp right now (5 → 40 over 45 days)
* **Sent** — successful deliveries in the last rolling 24 hours
* **Left** — headroom in that window

If **Left** is 0, further `sendEmail` nodes wait for a send to age out of the window. A send-email span that sits **pending** for hours is that wait. See [Sending](/mailboxes/sending#why-a-send-email-span-stays-pending).

### Step 5: Add a Send email node to a play

1. Open (or create) a [play](/plays/overview) on the contacts model
2. Add a **Send email** node from the palette (Sales)
3. Pick the mailbox, map **To** / **Subject** / **Body** from the record
4. For a reply, set **In reply to** and **References** so the thread stays together
5. Connect it downstream of whatever enriches or drafts the body

The visual node is the same `sendEmail` action `sendEmail()` emits in code. Re-deploying a changed project play overwrites canvas edits on that play — see [Code and UI round-trips](/deploy/state-and-drift#code-and-ui-round-trips).

### Step 6: Watch the thread

* Workspace **Emails** lists every thread across mailboxes
* A mailbox's **Emails** tab lists that inbox's threads
* Open a thread for the outbound copy, then opens, clicks, replies, and unsubscribes as they arrive

A recipient who clicks unsubscribe is added to the workspace suppression list and will not be mailed from any mailbox.

***

## Next steps

<CardGroup>
  <Card title="Overview" icon="envelope" href="/mailboxes/overview">
    Domains, mailbox types, folders, and the API.
  </Card>

  <Card title="Sending" icon="paper-plane" href="/mailboxes/sending">
    sendEmail(), the warm-up ramp, and per-mailbox pacing.
  </Card>

  <Card title="Build a play" icon="play" href="/plays/overview">
    Run sendEmail on each new row of a model.
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/workflows/overview">
    The TypeScript DSL sendEmail() lives in.
  </Card>
</CardGroup>


# MCP servers
Source: https://docs.getcargo.ai/mcp-servers/overview

Connect Cargo to Claude, ChatGPT, or Cursor with the platform MCP, or expose a curated set of tools, agents, and data models behind your own MCP server.

Cargo speaks [Model Context Protocol](https://modelcontextprotocol.io/) in two ways:

|                | **Platform MCP**                             | **Curated MCP server**                                      |
| -------------- | -------------------------------------------- | ----------------------------------------------------------- |
| URL            | `https://mcp.getcargo.io/mcp`                | `https://mcp.getcargo.io/v1/ai/mcpServers/<uuid>/mcp`       |
| Who can use it | Every workspace member, no setup             | Whoever you share that server with                          |
| Surface        | Search/execute actions, query models         | Only the tools, agents, models, and capabilities you listed |
| Best for       | “Connect Cargo” in ChatGPT / Claude / Cursor | A named, blessed picker for one client or use case          |

The UUID path is Cargo’s address for a workspace resource — not an MCP protocol requirement. Linear and Notion use `/mcp` the same way the platform server does. Keep curated servers on the UUID path; OAuth tokens are audience-bound to that exact URL.

Agent [skills](/skills/overview) over the `cargo-ai` CLI stay the right surface for building: project deploys, schema changes, and large batches.

## Connect the platform MCP

Hosted clients that speak HTTP (ChatGPT custom connectors, Claude.ai, Cursor over HTTP) connect to:

```
https://mcp.getcargo.io/mcp
```

The client discovers Cargo’s authorization server, opens a browser for you to sign in, and then calls the server with a short-lived access token. If you belong to more than one workspace, the consent screen asks which one to bind. Workspace API tokens still work as `Authorization: Bearer`.

On the MCP servers page, **Connect Cargo** shows this URL and the live OAuth grants against it.

### What it can do

The platform server is a small, stable tool list. It does **not** dump every CLI command or every workspace tool into the client’s picker.

* `whoami` / `get_usage` — signed-in user, workspace, and recent credit usage
* `search_actions` — search connector, native, tool, and agent actions
* `get_action_schema` — input and output JSON schemas for those actions, without running anything
* `execute_action` / `execute_action_batch` — run one input or a batch (credits apply)
* `get_run` / `get_batch` / `list_runs` — poll a run or batch; `get_run` returns the last node output (not computed configs or traces); a finished batch carries a time-limited download URL for its output CSV
* `list_models` / `describe_model` / `query_models` — the model catalog, one model's columns and its `dataset.model` reference, and one read-only SQL `SELECT` over them (joins and aggregates allowed; small row cap, so aggregate rather than page)
* `map_context` / `search_context` / `browse_context` / `read_context` — read the workspace's [context](/context/overview): `map_context` lists every indexed file with its title and summary, `search_context` returns matching lines, `read_context` returns a line range. Read-only — the platform server never writes to the context

`config` on a top-level action must be `{}`. Inputs go in `data` (single) or `records` (batch). Never fan `execute_action` out record-by-record — that is what `execute_action_batch` is for.

### Connect a coding agent

`cargo-ai mcp` serves the platform server over stdio with the credentials the CLI already has:

```bash theme={null}
claude mcp add cargo -- cargo-ai mcp
```

Pass `--server <uuid>` to bridge a curated server instead. With no `--server`, the bridge uses `CARGO_MCP_SERVER_UUID` if set, otherwise the platform `/mcp`.

<Note>
  stdout carries the MCP protocol and every log goes to stderr, so nothing else
  may write to stdout around the bridge.
</Note>

## Define a curated MCP server

Each member is passed by handle — the same rich refs an agent accepts:

```ts mcp/crm.ts theme={null}
import { defineMcpServer } from "@cargo-ai/cdk";
import { sdr } from "../agents/sdr";
import { contacts } from "../models/contacts";
import { enrich } from "../tools/enrich";

export const crmServer = defineMcpServer("crm", {
  description: "CRM tools and data for assistants.",
  // One array — tools, agents, and data models (same surface as an agent):
  uses: [enrich, sdr, { ref: contacts, readOnly: true }],
  capabilities: [
    "webSearch",
    { slug: "context", config: { isReadOnly: true } },
  ],
});
```

### Deploy

```bash theme={null}
cargo-ai project deploy
cargo-ai ai mcp-server list   # note the server's uuid
```

### Connect a remote MCP client

```
https://mcp.getcargo.io/v1/ai/mcpServers/<uuid>/mcp
```

OAuth accepts any `https` callback, plus loopback for local clients. On the MCP server page, **Connected apps** lists each live OAuth grant. Revoke a grant to sign that client out; it will need to authorize again.

### MCP or the agent skills?

|          | **MCP**                                                         | **[Agent skills](/skills/overview)**                                        |
| -------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Surface  | Platform: operate the workspace. Curated: only what you exposed | The whole `cargo-ai` CLI                                                    |
| Reaches  | Any MCP client, including ones with no skills support           | Claude Code, Cursor, Codex, and other [skills.sh](https://skills.sh) agents |
| Best for | In-conversation calls against a workspace                       | Batches, workflows, schema changes, deploys, anything with a cost gate      |

Rule of thumb: more than a handful of records, or anything worth re-running, belongs in the CLI. Never fan an MCP tool out record-by-record over a list — that is what a batch is for, and it is cheaper and observable.

## From the CLI

Servers can also be created and edited without a project:

```bash theme={null}
cargo-ai ai mcp-server create --name "GTM tools" \
  --actions '[{"slug":"<tool-or-agent-uuid>","kind":"tool","name":null,"description":null,"isBulkAllowed":false,"config":{}}]'
cargo-ai ai mcp-server update --uuid <uuid> --name "GTM tools"
```

Actions take `kind: "tool"` or `kind: "agent"` — an agent can be exposed as a callable MCP tool. `update` replaces the `--actions`, `--resources`, and `--capabilities` arrays wholesale rather than merging, so read the current server first and pass the full array back. Capabilities such as `webSearch` and `context` become MCP tools on the server.


# Track workspace activities
Source: https://docs.getcargo.ai/models/activities

Track and analyze activities data from Cargo tools and plays using SQL queries

The activities data table associated with your workspace logs record enrolments, node executions, and success/failure outcomes across all your tools and plays.

These logs provide real-time visibility into how your workflows are performing—helping you identify bottlenecks, debug errors, and discover optimization opportunities.

<Info>
  You can query activities data from your **data warehouse's query editor**, a
  Cargo **data model**, or the **Sandbox** query editor in the System of Record
  section of your workspace settings.
</Info>

<Note>
  Adapt query syntax for your database (BigQuery or Snowflake). If using your
  own data warehouse, the dataset name matches the **Dataset name** from your
  System of Record configuration. If using Cargo's managed BigQuery, contact
  the Cargo team for connection details.
</Note>

## Query from the CLI

Run these queries directly against your system of record with the CLI:

```bash theme={null}
cargo-ai storage query execute \
  "SELECT kind, COUNT(*) AS count FROM activities
   WHERE kind IN ('workflowEntered','workflowLeft') GROUP BY kind"
```

With `storage query`, reference the activities table simply as `activities` — Cargo rewrites it to the correct physical table for your warehouse. The physical `compute__activities` / `_compute.activities` names in the [Table naming conventions](#table-naming-conventions) section below are only needed when querying your warehouse directly.

## Understanding the activities table

The activities data is stored in the `compute__activities` table with the following structure:

| Column          | Description                                          |
| --------------- | ---------------------------------------------------- |
| `_id`           | Unique identifier for each activity                  |
| `_time`         | Timestamp when the activity occurred                 |
| `kind`          | Type of activity (see below)                         |
| `model_uuid`    | Reference to the data model (if applicable)          |
| `workflow_uuid` | Reference to the workflow                            |
| `play_uuid`     | Reference to the play (if applicable)                |
| `tool_uuid`     | Reference to the tool (if applicable)                |
| `segment_uuid`  | Reference to the segment (for segment activities)    |
| `context`       | JSON object containing detailed activity information |

### Activity types

| Kind                   | Description                                       |
| ---------------------- | ------------------------------------------------- |
| `workflowNodeExecuted` | A specific node in a workflow completed execution |
| `workflowEntered`      | A record entered a workflow                       |
| `workflowLeft`         | A record exited a workflow                        |
| `segmentEntered`       | A record entered a segment                        |
| `segmentLeft`          | A record left a segment                           |

## Example: Track workflow node executions

Query all node executions for a specific workflow, including their status and any error messages:

<Tabs>
  <Tab title="BigQuery">
    ```sql theme={null}
    SELECT
      _time,
      JSON_VALUE(context, '$.nodeSlug') AS node_name,
      JSON_VALUE(context, '$.nodeKind') AS node_type,
      JSON_VALUE(context, '$.nodeStatus') AS status,
      JSON_VALUE(context, '$.nodeErrorMessage') AS error_message
    FROM [DATASET].compute__activities
    WHERE kind = 'workflowNodeExecuted'
      AND JSON_VALUE(context, '$.workflowUuid') = 'your-workflow-uuid-here'
    ORDER BY _time DESC;
    ```
  </Tab>

  <Tab title="Snowflake">
    ```sql theme={null}
    SELECT
      _time,
      context:nodeSlug AS node_name,
      context:nodeKind AS node_type,
      context:nodeStatus AS status,
      context:nodeErrorMessage AS error_message
    FROM [DATABASE]._compute.activities
    WHERE kind = 'workflowNodeExecuted'
      AND context:workflowUuid = 'your-workflow-uuid-here'
    ORDER BY _time DESC;
    ```
  </Tab>
</Tabs>

## Example: Track workflow throughput

Monitor how many records enter and exit your workflows over time:

<Tabs>
  <Tab title="BigQuery">
    ```sql theme={null}
    SELECT
      DATE(_time) AS date,
      kind,
      COUNT(*) AS count
    FROM [DATASET].compute__activities
    WHERE kind IN ('workflowEntered', 'workflowLeft')
      AND workflow_uuid = 'your-workflow-uuid-here'
    GROUP BY date, kind
    ORDER BY date DESC;
    ```
  </Tab>

  <Tab title="Snowflake">
    ```sql theme={null}
    SELECT
      DATE(_time) AS date,
      kind,
      COUNT(*) AS count
    FROM [DATABASE]._compute.activities
    WHERE kind IN ('workflowEntered', 'workflowLeft')
      AND workflow_uuid = 'your-workflow-uuid-here'
    GROUP BY date, kind
    ORDER BY date DESC;
    ```
  </Tab>
</Tabs>

## Example: Identify failing nodes

Find nodes with the highest error rates:

<Tabs>
  <Tab title="BigQuery">
    ```sql theme={null}
    SELECT
      JSON_VALUE(context, '$.nodeSlug') AS node_name,
      COUNT(*) AS total_executions,
      COUNTIF(JSON_VALUE(context, '$.nodeStatus') = 'failed') AS failures,
      ROUND(
        COUNTIF(JSON_VALUE(context, '$.nodeStatus') = 'failed') * 100.0 / COUNT(*),
        2
      ) AS failure_rate
    FROM [DATASET].compute__activities
    WHERE kind = 'workflowNodeExecuted'
      AND _time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
    GROUP BY node_name
    HAVING failures > 0
    ORDER BY failure_rate DESC;
    ```
  </Tab>

  <Tab title="Snowflake">
    ```sql theme={null}
    SELECT
      context:nodeSlug AS node_name,
      COUNT(*) AS total_executions,
      COUNT_IF(context:nodeStatus = 'failed') AS failures,
      ROUND(COUNT_IF(context:nodeStatus = 'failed') * 100.0 / COUNT(*), 2) AS failure_rate
    FROM [DATABASE]._compute.activities
    WHERE kind = 'workflowNodeExecuted'
      AND _time >= DATEADD(DAY, -7, CURRENT_TIMESTAMP())
    GROUP BY node_name
    HAVING failures > 0
    ORDER BY failure_rate DESC;
    ```
  </Tab>
</Tabs>

## Table naming conventions

Depending on your System of Record scope, use the appropriate table reference:

| Scope                    | Table reference                              |
| ------------------------ | -------------------------------------------- |
| BigQuery project-level   | `[PROJECT_ID].[DATASET].compute__activities` |
| BigQuery dataset-level   | `[DATASET].compute__activities`              |
| Snowflake database-level | `[DATABASE]._compute.activities`             |
| Snowflake schema-level   | `[DATABASE].[SCHEMA]._compute__activities`   |

<Tip>
  Replace bracketed values (e.g., `[PROJECT_ID]`, `[DATASET]`) with your actual
  configuration values from the System of Record settings.
</Tip>


# Extractors
Source: https://docs.getcargo.ai/models/extractors

How a connector action becomes a model's data source — the extractSlug and config that populate an integration-backed model.

An **extractor** is the connector action that populates a model. When you point `defineModel` at a connector's dataset, `extractSlug` chooses *which* action fetches the rows and `config` parameterizes it.

## The shape

```ts models/contacts.ts theme={null}
import { defineModel } from "@cargo-ai/cdk";
import { hubspot } from "../connectors/hubspot";

export const contacts = defineModel("contacts", {
  connector: hubspot,             // the connector whose dataset backs this model
  extractSlug: "fetchRecords",  // the connector's extract action
  config: {                     // action-specific parameters
    objectType: "contacts",
    columnSelectionMode: "all",
  },
  schedule: { type: "cron", cron: "0 * * * *" },
});
```

| Field         | Purpose                                                                       |
| ------------- | ----------------------------------------------------------------------------- |
| `dataset`     | The connector handle whose dataset this model reads from.                     |
| `extractSlug` | The connector action that returns rows (e.g. `fetchRecords`).                 |
| `config`      | Parameters for that action — the object type, filters, column selection, etc. |
| `schedule`    | How often to re-extract (`cron`, or omit for manual refresh).                 |

## Discovering slugs and config

The valid `extractSlug` values and their `config` shape are per-integration. Discover them by generating types or querying the integration:

```bash theme={null}
cargo-ai project types                              # types extractSlug/config in your editor
cargo-ai connection integration get <slug>      # the integration's actions and extractors
```

Each connector page in [Integrations](/integration/overview) lists the extractor actions available for that system.

## Refreshing

A model re-extracts on its `schedule`, or on demand:

```bash theme={null}
cargo-ai storage model refresh <model-uuid>
```

<Note>
  Integration-backed models are read-only mirrors — the source system stays the
  source of truth. To write back, use the integration's write actions in a
  [workflow](/workflows/overview), or use an
  [object model](/models/object-models) for data Cargo owns.
</Note>


# Object models
Source: https://docs.getcargo.ai/models/object-models

Native, writable data models for the core entities of your GTM motion

Object models are **native, Cargo-managed data models** for the core entities your team works with — accounts, contacts, deals, leads, and any custom object you need. Unlike integration models that mirror data from an external source, object models are owned by your workspace: your plays, tools, and agents create, update, and remove records in them directly.

Use object models when you need a writable system of record inside Cargo — store companies, contacts, deals and custom objects, sync GTM data into them, unify across sources. Built for scale rather than an application database. For example, a list of qualified leads built from research, a pipeline of opportunities sourced from intent signals, or a custom catalog of partners, products, or territories that doesn't live anywhere else.

## Create an object model from the CLI

Object models are owned by Cargo. You can create them and their columns imperatively with the `storage` commands, or declaratively in code in a project ([see below](#define-an-object-model-in-code)):

```bash theme={null}
cargo-ai storage dataset list                     # → the native datasetUuid

# Create a custom object model
cargo-ai storage model create \
  --slug sourced_leads --name "Sourced Leads" \
  --dataset-uuid <datasetUuid> --extractor-slug csv --config '{}'

# Add columns
cargo-ai storage column create --model-uuid <model-uuid> \
  --column '{"slug":"email","type":"string","label":"Email","kind":"custom"}'
cargo-ai storage column create --model-uuid <model-uuid> \
  --column '{"slug":"website","type":"string","label":"Website","kind":"custom"}'
```

<Note>
  Object models are stored in the same data warehouse as your integration
  models (managed BigQuery, or your own BigQuery or Snowflake), so you can join,
  query, and unify them with SQL, at warehouse scale.
  The built-in `Account` / `Contact` / `Deal` / `Lead` types ship pre-shaped —
  you only add columns for fields beyond their standard schema.
</Note>

## Define an object model in code

Not every model sits behind a connector. In a [project](/get-started/project-layout), pass `kind: "native"` to [`defineModel`](/models/overview) to declare an object model in the workspace's built-in dataset — `defineCustom` for a free-form schema, or the CRM-shaped `defineAccount` / `defineContact` / `defineDeal` / `defineLead`:

```ts models/companies.ts theme={null}
import { defineModel } from "@cargo-ai/cdk";

export const companies = defineModel("companies", {
  kind: "native",
  extractSlug: "defineCustom",
  config: { columns: [{ slug: "domain", type: "string" }] },
});
```

<Note>
  Deploying binds the model into this project's deploy state, so your plays, tools, and
  agents can reference it by handle. To adopt one of the four **unified** models
  from code instead, see [Unification](/models/unification#reference-a-unified-model-in-code).
</Note>

## Link models with relationships

[Relationships](/models/relationships) join two object models in the same dataset. Declare them in code with `defineRelationship`, referencing the CLI-created models by `modelRef(uuid)`:

```ts relationships/contact-account.ts theme={null}
import { defineRelationship, modelRef } from "@cargo-ai/cdk";

export const contactAccount = defineRelationship("contact-account", {
  from: { model: modelRef("<contacts-uuid>"), column: "account_id" },
  to: { model: modelRef("<accounts-uuid>"), column: "id" },
  relation: "manyToOne",
});
```

<Note>
  Not using a project? Set the same join from the CLI with `cargo-ai storage
      relationship set --dataset-uuid <uuid> --relationships '<json array>'` — see
  [Relationships](/models/relationships) for the field reference.
</Note>

***

## When to use object models

| Scenario                                    | Why an object model fits                                                                                  |
| :------------------------------------------ | :-------------------------------------------------------------------------------------------------------- |
| **Build a sourced lead list**               | Capture leads from research, scraping, or signals before they exist in your CRM.                          |
| **Maintain an internal pipeline**           | Track deals, accounts, or campaigns that aren't synced from a connected system.                           |
| **Persist agent and play outputs**          | Let agents write structured results (qualified accounts, recommended plays, etc.) into a queryable table. |
| **Model entities you don't have a CRM for** | Partners, vendors, products, territories, content assets, or any custom object specific to your business. |
| **Unify writable data with integrations**   | Object Account / Contact records participate in [unification](/models/unification) like any source.       |

For models that **mirror** data from an external system (HubSpot, Salesforce, Snowflake, a webhook, etc.), use [integration models](/models/overview#model-types) instead.

***

## Built-in object types

Cargo ships five native object types. The first four come pre-shaped with the standard fields for their entity, so you can start writing records immediately and they will participate in unification out of the box.

<CardGroup>
  <Card title="Account" icon="building">
    A company. Pre-mapped with `name`, `website`, `linkedin_url`, `industry`,
    `number_of_employees`, `annual_revenue`, billing address, owner, and parent
    account.
  </Card>

  <Card title="Contact" icon="user">
    A person tied to an account. Pre-mapped with first/last name, `email`,
    `phone`, `title`, `linkedin_url`, mailing address, lead source, and owner.
  </Card>

  <Card title="Deal" icon="circle-dollar">
    An opportunity tied to an account. Pre-mapped with `amount`,
    `stage_name`, `close_date`, `probability`, `forecast_category`,
    `is_closed`, `is_won`, owner, and campaign.
  </Card>

  <Card title="Lead" icon="user-plus">
    An unqualified person + company combined into one record. Includes
    conversion fields (`is_converted`, `converted_account_id`,
    `converted_contact_id`, `converted_opportunity_id`) for handoff to
    Account/Contact.
  </Card>

  <Card title="Custom" icon="table">
    An object you define from scratch. Pick the columns and types you need —
    `string`, `number`, `boolean`, `date`, `object`, `array`, or `vector`.
  </Card>
</CardGroup>

Each built-in type has a default `id` column (a Cargo-generated UUID on insert) and a sensible title column (`name` for Account/Contact/Deal/Lead, `id` for Custom).

<Tip>
  Need a field that isn't on the built-in schema? Add a [custom
  column](/models/overview) with `storage column create` — your plays can
  upsert values into it without changing the underlying schema.
</Tip>

***

## How object models compare

| Capability                            | Object model                        | Integration model                          | Unified model                    |
| :------------------------------------ | :---------------------------------- | :----------------------------------------- | :------------------------------- |
| Source of records                     | Cargo plays, agents, tools, API     | External system (CRM, warehouse, webhook…) | Computed from other models       |
| Writable from a workflow              | ✅ Insert / update / upsert / remove | ❌ Use the integration's own write actions  | ❌ Read-only                      |
| Schema control                        | ✅ Built-in or fully custom          | ❌ Fixed by the source                      | ❌ Fixed by Cargo                 |
| Participates in unification           | ✅ Account & Contact types           | ✅ When the integration declares a type     | n/a (it *is* the unified output) |
| Triggers plays on change              | ✅                                   | ✅                                          | ✅                                |
| Available in Model search / Model ask | ✅                                   | ✅                                          | ✅                                |

***

## Writing to an object model

Object models are designed to be written to from inside Cargo — from the storage steps in a [workflow](/workflows/overview) that backs a play or tool. The Storage actions below all target object models specifically; when you pick a model in the node configuration, only object models appear in the picker.

| Action           | What it does                                                 |
| :--------------- | :----------------------------------------------------------- |
| **Model insert** | Add one or more new records. The `id` is generated by Cargo. |
| **Model update** | Update records matching a column / value pair.               |
| **Model upsert** | Update matching records, or insert a new one if none match.  |
| **Model remove** | Delete records matching a column / value pair.               |

<Steps>
  <Step title="Pick a target object model">
    Use the **Model** dropdown on any of the actions above. The dropdown is
    scoped to native objects — integration models and unified models are
    intentionally hidden.
  </Step>

  <Step title="(For update / upsert / remove) choose a matching column">
    Cargo will resolve every record where the matching column equals the
    matching value. Use a unique column (typically `id`, `email`, or `website`)
    to avoid touching unintended rows.
  </Step>

  <Step title="Map the values">
    Provide a value for each column you want to write. Values support
    [expressions](/reference/expressions-cheatsheet) (e.g.
    `{{nodes.start.email}}`).
  </Step>
</Steps>

<Warning>
  `id` is generated by Cargo on insert and cannot be supplied. For updates and
  upserts, do **not** include `id` in the column mappings — use it as the
  matching column instead.
</Warning>

***

## Object models and unification

`Account` and `Contact` object models declare a [unification type](/models/unification) by default, so the records you write into them roll up into the unified `Account` and `Contact` models alongside your CRM, enrichment, and other sources.

| Object type | Unifies as | Default reference columns                                                                              |
| :---------- | :--------- | :----------------------------------------------------------------------------------------------------- |
| **Account** | `account`  | `website` → `domain`, `name` → `slug`, `linkedin_url` → `linkedinHandle`, `linkedin_id` → `linkedinId` |
| **Contact** | `contact`  | `email` → `email`, `linkedin_url` → `linkedinHandle`, `linkedin_id` → `linkedinId`                     |
| **Deal**    | `account`  | (no default reference columns — link via `account_id`)                                                 |

This means an account you create from a research agent, a contact you upsert from a webhook, and a company synced from HubSpot all collapse into the same canonical record when they share a domain or LinkedIn identifier.

<Note>
  Lead and Custom object models don't participate in unification. Convert leads
  to Account / Contact records (using the `converted_account_id` /
  `converted_contact_id` fields) once they qualify.
</Note>

***

## Querying object models

Like every model in Cargo, object models materialize as a table in your data warehouse. They follow the same [table naming convention](/models/querying) as integration models, under the `native` dataset:

```sql theme={null}
SELECT *
FROM CARGO_DB.datasets_native.models_<MODEL_SLUG>
```

You can join object models with integration or unified models freely — for example, find every sourced lead whose company already exists in your unified `Account` model:

```sql theme={null}
SELECT
  l.id            AS lead_id,
  l.email,
  l.company,
  a.id            AS unified_account_id
FROM CARGO_DB.datasets_native.models_sourced_leads l
LEFT JOIN CARGO_DB.object.accounts a
  ON LOWER(l.website) = a.domain
WHERE a.id IS NOT NULL
```

***

## Next steps

<CardGroup>
  <Card title="Models overview" icon="table" href="/models/overview">
    See how object models fit alongside integration and unified models.
  </Card>

  <Card title="Unification" icon="diagram-project" href="/models/unification">
    Learn how Account and Contact object records merge with CRM and enrichment
    data.
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/workflows/overview">
    Insert, update, upsert, and remove records from your plays and tools.
  </Card>

  <Card title="Querying data" icon="code" href="/models/querying">
    Query object models with SQL alongside the rest of your warehouse.
  </Card>
</CardGroup>


# Overview
Source: https://docs.getcargo.ai/models/overview

Structured, queryable tables that power your plays and workflows. Define them in code with defineModel, sourced from a connector or owned by Cargo.

A **data model** is a structured table in your Cargo warehouse. Models feed play triggers, back model-search steps, and give agents structured context. You define them in code with `defineModel`.

## Define a model

A model sourced from a connector's dataset wires to the connector by handle and pulls rows with an **extractor**:

```ts models/contacts.ts theme={null}
import { defineModel } from "@cargo-ai/cdk";
import { hubspot } from "../connectors/hubspot";

export const contacts = defineModel("contacts", {
  connector: hubspot,            // handle — connector deploys first, dataset injected
  extractSlug: "fetchRecords", // which connector action populates the table
  config: { objectType: "contacts", columnSelectionMode: "all" },
  schedule: { type: "cron", cron: "0 * * * *" }, // refresh hourly
});
```

See [Extractors](/models/extractors) for how a connector action becomes a model's data source.

## Model types

Models live side-by-side in the same warehouse and can be queried, joined, and used as triggers. What differs is who owns the schema and who writes the rows.

| Type            | Schema owner             | Writable from a workflow                 | Typical use                                             |
| --------------- | ------------------------ | ---------------------------------------- | ------------------------------------------------------- |
| **Object**      | You (built-in or custom) | Yes                                      | Sourced lists, internal pipelines, custom entities      |
| **Integration** | The connected source     | No — use the integration's write actions | Mirror CRM, warehouse, webhook, or file data            |
| **Unified**     | Cargo                    | Read-only                                | One deduplicated view of accounts, contacts, and events |

* [Object models](/models/object-models) — native, writable `Account` / `Contact` / `Deal` / `Lead` or custom schemas.
* [Unification](/models/unification) — read-only merged views across all sources.
* [Querying data](/models/querying) — SQL over your models.
* [Segments](/models/segments) — named, filtered views defined with `defineSegment`.
* [Activities](/models/activities) — event models.

## Capabilities

* **Change-based triggers** — plays react in real time to added / updated / removed rows.
* **[Segments](/models/segments)** — named, filtered views that batches, exports, and plays target.
* **[Relationships](/models/relationships)** — join models on shared columns with `defineRelationship`.
* **Additional columns** — custom, computed, and metric columns extend a model without touching the source.

## From the CLI

```bash theme={null}
cargo-ai storage model list                  # → modelUuid
cargo-ai storage model get-ddl <model-uuid>  # exact SQL table name
cargo-ai storage model refresh <model-uuid>
```

## Using the UI

Build the same models in the web app — see [Using the UI](/models/using-ui) for the visual walkthrough of object models, integration loaders (native, webhook, SQL), and relationships.

<Note>
  Cargo hosts your models on a data warehouse. By default you get a managed
  Snowflake instance, or connect your own — see [Snowflake](/integration/snowflake)
  and [BigQuery](/integration/big-query).
</Note>


# Querying Cargo data
Source: https://docs.getcargo.ai/models/querying

Access your Cargo data models directly via SQL

Every data model you create in Cargo — whether an [object model](/models/object-models), an integration model, or a unified model — is stored as a table in your connected data warehouse. You can query these tables directly using SQL, whether from your own BI tools, data pipelines, or within Cargo to create new SQL-based models.

## Query from the CLI

The fastest path is `cargo-ai storage query`. Reference each model **logically** as `<dataset-slug>.<model-slug>` — Cargo validates it against your models and rewrites it to the real warehouse table, so you never hand-build a physical table name:

```bash theme={null}
cargo-ai storage model list                    # → your models and their dataset/model slugs
cargo-ai storage model get-ddl <model-uuid>    # → exact column names + types

cargo-ai storage query execute \
  "SELECT COUNT(*) AS total FROM crm.companies WHERE employee_count > 500"
# → {"outcome":"queried","rows":[{"total":142}]}
```

<Warning>
  In `storage query`, every table **must** be written as
  `<dataset-slug>.<model-slug>` (e.g. `crm.companies`) — a bare name or a physical
  warehouse name is rejected. Only `SELECT` statements are allowed. Run
  `model get-ddl` to confirm the exact column names and types before querying.
</Warning>

***

## Table naming conventions

How you name a table depends on **how** you query.

### In `cargo-ai storage query` (recommended)

Reference models logically as `<dataset-slug>.<model-slug>`:

```sql theme={null}
SELECT * FROM crm.companies      -- connector-backed model
SELECT * FROM object.accounts    -- object / unified model
```

Cargo rewrites the reference to the real warehouse table, so the same query works whether your system of record is BigQuery or Snowflake.

### Directly in your warehouse (BI tools, SQL console)

Querying the warehouse directly uses the **physical** table name, which depends on your warehouse and its configured scope. The building blocks are the schema `datasets_<connector-slug>` and the table `models_<model-slug>`:

**BigQuery**

| Scope   | Physical table                                                   |
| ------- | ---------------------------------------------------------------- |
| Dataset | `` `<project>.<dataset>.datasets_<connector>__models_<model>` `` |
| Project | `` `<project>.<prefix>_datasets_<connector>.models_<model>` ``   |

**Snowflake**

| Scope    | Physical table                                             |
| -------- | ---------------------------------------------------------- |
| Database | `<DATABASE>.datasets_<connector>.models_<model>`           |
| Schema   | `<DATABASE>.<SCHEMA>.datasets_<connector>__models_<model>` |

<Note>
  In the single-container scopes (BigQuery **dataset**, Snowflake **schema**) the
  connector and model parts are joined with a double underscore (`__`). Always
  confirm the exact physical name with `cargo-ai storage model get-ddl <model-uuid>`.
</Note>

***

## Query examples

These run through `cargo-ai storage query` using logical `<dataset>.<model>` references. To run them directly in your warehouse instead, substitute the physical table names from the conventions above.

### Basic query

```sql theme={null}
SELECT
  company,
  website,
  funding_amt,
  funding_type
FROM file.abm_raw
WHERE funding_amt > 1000000
```

### Joining multiple models

Combine data from different Cargo models:

```sql theme={null}
SELECT
  a.company,
  a.website,
  b.enrichment_data,
  c.activity_score
FROM crm.companies a
LEFT JOIN enrichment.company_data b
  ON a.domain = b.domain
LEFT JOIN analytics.scores c
  ON a.company_id = c.company_id
```

### Aggregations

```sql theme={null}
SELECT
  company,
  website,
  SUM(deal_value) as total_pipeline,
  COUNT(*) as deal_count
FROM crm.deals
WHERE stage != 'Closed Lost'
GROUP BY company, website
HAVING SUM(deal_value) > 10000
```

***

## Creating SQL models

You can create new Cargo data models by writing SQL queries against your existing tables. This is useful for combining data from multiple sources, applying transformations, or creating aggregated views.

<img alt="SQL model configuration" />

<Steps>
  <Step title="Add a new SQL model">
    Navigate to your data models and create a new model. Select **SQL** as the object type.
  </Step>

  <Step title="Write your SQL query">
    Write a query that selects data from your existing Cargo tables using the naming conventions above.

    ```sql theme={null}
    SELECT
      "company",
      "_emitted_at" AS emitted_at,
      "website",
      "hq",
      "funding_amt",
      "funding_type",
      "funding_date"
    FROM CARGO_DB.datasets_file.models_abm_lk
    ```

    <Warning>
      Do not include `_id`, `_time`, `_title`, or `_segments` columns in your query—these are system columns that Cargo generates automatically. Column names also cannot start with `computed__`, `custom__`, or `metric__`, or contain `___` or `$`.
    </Warning>
  </Step>

  <Step title="Configure column mapping">
    Map the required columns:

    * **ID** — The unique identifier for each record
    * **Title** — A human-readable label for records
  </Step>

  <Step title="Preview and save">
    Preview the query results to verify your data, then save the model.
  </Step>
</Steps>

***

## Next steps

<CardGroup>
  <Card title="Workflows" icon="diagram-project" href="/workflows/overview">
    Use model search, record, and custom column actions.
  </Card>

  <Card title="BigQuery setup" icon="database" href="/integration/big-query">
    Configure BigQuery as your data warehouse.
  </Card>

  <Card title="Snowflake setup" icon="snowflake" href="/integration/snowflake">
    Configure Snowflake as your data warehouse.
  </Card>
</CardGroup>


# Relationships
Source: https://docs.getcargo.ai/models/relationships

Join two models on shared columns — define them in code with defineRelationship so plays, metrics, and queries can traverse between related records.

A **relationship** is a join between two [models](/models/overview) in the same dataset: it links a column on a `from` model to a column on a `to` model with a cardinality (`oneToOne`, `oneToMany`, or `manyToOne`). Relationships let metric columns aggregate across related records and let queries traverse from one model to another. You define one in code with `defineRelationship`.

## Define a relationship

Wire each side to a model by handle, so both models deploy before the relationship and their uuids are injected automatically:

```ts relationships/contact-account.ts theme={null}
import { defineRelationship } from "@cargo-ai/cdk";
import { accounts } from "../models/accounts";
import { contacts } from "../models/contacts";

export const contactAccount = defineRelationship("contact-account", {
  from: { model: contacts, column: "account_id" },
  to: { model: accounts, column: "id" },
  relation: "manyToOne",
});
```

| Field                           | Role                                                                                                                                     |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `from`                          | The referencing side — `{ model, column }`. `model` is a model handle or `modelRef(uuid)`; `column` is the slug holding the foreign key. |
| `to`                            | The referenced side — `{ model, column }`, typically the target's identifier column (e.g. `id`).                                         |
| `relation`                      | Cardinality: `oneToOne`, `oneToMany`, or `manyToOne`.                                                                                    |
| `from.property` / `to.property` | Optional. Navigate into a JSON (`object` / `array`) column value, e.g. `"hubspot___companies[0]"`. Only valid on JSON-typed columns.     |

<Note>
  Both models must live in the **same dataset** — the dataset is derived from
  the `from` model at deploy. Relationships have no server-side slug, so the
  `defineRelationship` slug is a local identifier only; the deployed
  relationship is tracked by its state uuid.
</Note>

<Tip>
  A `defineRelationship` only manages the row it declares — relationships you
  create in the UI or by other means on the same dataset are left untouched. On
  destroy, only the managed relationship is removed.
</Tip>

## From the CLI

Relationships are set per dataset as a JSON array. List the datasets to find the `datasetUuid`, then set one or more relationships:

```bash theme={null}
cargo-ai storage dataset list                     # → datasetUuid
cargo-ai storage relationship list                # existing relationships

cargo-ai storage relationship set \
  --dataset-uuid <datasetUuid> \
  --relationships '[{"fromModelUuid":"<contacts-uuid>","fromColumnSlug":"account_id","toModelUuid":"<accounts-uuid>","toColumnSlug":"id","relation":"manyToOne"}]'
```

<Warning>
  `relationship set` is a **per-dataset replace**: the payload becomes the full
  set of manually-managed relationships for that dataset, so include every
  relationship you want to keep. (Auto-generated unification relationships are
  managed separately and aren't affected.)
</Warning>

## Next steps

<CardGroup>
  <Card title="Models overview" icon="table" href="/models/overview">
    How relationships fit alongside a model's columns and segments.
  </Card>

  <Card title="Object models" icon="cube" href="/models/object-models">
    Link native `Account` / `Contact` / `Deal` records to each other.
  </Card>

  <Card title="Querying data" icon="database" href="/models/querying">
    Join related models with SQL in your warehouse.
  </Card>

  <Card title="Deploying" icon="rocket" href="/deploy/deploying">
    The reconcile lifecycle that creates and updates relationships.
  </Card>
</CardGroup>


# Segments
Source: https://docs.getcargo.ai/models/segments

Named, filtered views of a model — define them in code with defineSegment and target them from batches, exports, and change feeds.

A **segment** is a named, filtered view of a [model](/models/overview): the records matching a filter, optionally sorted, limited, and scoped to specific columns. Segments are what you point batches, exports, and change feeds at. You define one with `defineSegment`.

## Define a segment

```ts segments/us-icp.ts theme={null}
import { defineSegment } from "@cargo-ai/cdk";
import { contacts } from "../models/contacts";

export const usIcp = defineSegment("us-icp", {
  model: contacts,
  filter: {
    conjonction: "and",
    groups: [{
      conjonction: "and",
      conditions: [
        { kind: "string", columnSlug: "country", operator: "is", values: ["US"] },
        { kind: "number", columnSlug: "employee_count", operator: "greaterThan", values: [50] },
      ],
    }],
  },
  sort: [{ columnSlug: "employee_count", kind: "desc" }],
  limit: 1000,
});
```

| Field                 | Role                                                                                                                                                     |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`               | The model this segment filters — a model handle or `modelRef(uuid)`. **Fixed at create**; changing it means a new segment.                               |
| `filter`              | Which records the segment includes — the same JSON shape as play [eligibility filters](/plays/triggering#eligibility-filter) and the UI segment builder. |
| `sort` / `limit`      | Optional ordering and cap on the view.                                                                                                                   |
| `trackingColumnSlugs` | Columns whose changes feed the segment's change feed.                                                                                                    |
| `columnSlugs`         | Columns the segment exposes (defaults to all).                                                                                                           |

<Note>
  The server derives the segment's own slug from its `name` (which defaults to
  the title-cased code slug), and the segment is state-tracked and adopted by
  name — so re-deploying the same definition reattaches rather than duplicates.
</Note>

To reference a segment that already exists in the workspace instead of defining it, use `segmentRef("<segment-uuid>")` — see [Referencing existing resources](/deploy/deploying#referencing-existing-resources).

## Use a segment

Run a play across a segment as a batch, or export its records:

```bash theme={null}
cargo-ai segmentation segment list                    # → segmentUuid
cargo-ai orchestration batch create \
  --workflow-uuid <uuid> \
  --data '{"kind":"segment","segmentUuid":"<uuid>"}' \
  --wait-until-finished

cargo-ai segmentation segment fetch --model-uuid <model-uuid>      # records as JSON
cargo-ai segmentation segment download --model-uuid <model-uuid>   # records as a file
```

<Warning>
  `segment fetch` and `segment download` take `--model-uuid`, not
  `--segment-uuid` — they query a model with segment-style filters.
</Warning>

## Next steps

<CardGroup>
  <Card title="Plays" icon="play" href="/plays/triggering">
    Trigger automations over the rows a segment tracks.
  </Card>

  <Card title="Querying data" icon="database" href="/models/querying">
    SQL over the models behind your segments.
  </Card>
</CardGroup>


# Unification
Source: https://docs.getcargo.ai/models/unification

How Cargo merges records from multiple integrations into unified account, contact, and event models

Unification is the process of merging records from your connected integrations and [object models](/models/object-models) into a single, deduplicated view. When you connect multiple data sources (CRMs, enrichment tools, analytics platforms) or write into native `Account` / `Contact` object models, Cargo automatically resolves and links records that represent the same real-world entity using shared identifiers called **references**.

The result is four native data models that serve as the canonical source of truth for your workspace: **Account**, **Contact**, **Account Event**, and **Contact Event**.

Unification runs automatically — there's nothing to deploy. You consume the unified models like any other, from the CLI or SQL:

```bash theme={null}
cargo-ai storage model list                    # → the unified Account / Contact models
cargo-ai storage model get-ddl <model-uuid>    # exact column names + types
cargo-ai storage query execute \
  "SELECT id, domain FROM object.accounts LIMIT 10"
```

***

## Reference a unified model in code

The four unified models are generated by Cargo's unification — they can't be created. In a [project](/get-started/project-layout), declaring one with its unify extractor **adopts** the live model instead of creating it: deploy binds the handle and reconciles its updatable surface (name, description, additional columns, sync schedule, and — on the entity models — the unification settings `config`), and destroy releases it. The handle then works anywhere a model is referenced:

```ts models/contacts.ts theme={null}
import { defineModel, defineSegment } from "@cargo-ai/cdk";

export const contacts = defineModel("contacts", {
  kind: "native",
  extractSlug: "unifyContacts",
});

export const reachable = defineSegment("reachable_contacts", {
  model: contacts,
  filter: {
    conjonction: "and",
    groups: [
      {
        conjonction: "and",
        conditions: [
          {
            kind: "string",
            columnSlug: contacts.columns.work_email,
            operator: "isNotEmpty",
          },
        ],
      },
    ],
  },
});
```

The unify extractor slugs are `unifyAccounts`, `unifyContacts`, `unifyAccountEvents`, and `unifyContactEvents` — one per unified model.

***

## How unification works

<Steps>
  <Step title="Connect data sources">
    Connect integrations (HubSpot, Salesforce, LinkedIn, etc.) that sync data models into your warehouse. Each integration model declares which **unification type** it participates in — `account`, `contact`, `accountEvent`, or `contactEvent`.
  </Step>

  <Step title="Map references">
    Each source model maps its columns to **unification references** — shared identifiers like `domain`, `email`, or `linkedinId`. Cargo uses these references to determine which records across different sources represent the same entity.
  </Step>

  <Step title="Resolve canonical IDs">
    Cargo builds a mapping table that groups records sharing the same reference values under a single **canonical ID**. If a HubSpot company and a Salesforce account share the same domain, they receive the same canonical ID.
  </Step>

  <Step title="Materialize unified models">
    The native unified models are materialized as tables in your warehouse, refreshed every 12 hours by default. The sync schedule is editable per model, down to a minimum interval of 5 minutes.
  </Step>
</Steps>

***

## Unified models

### Account

The Account model merges company records from all connected integrations into a single, deduplicated table. Each row represents a unique company, identified by a canonical ID computed from shared references.

| Column                 | Type     | Description                                                         |
| :--------------------- | :------- | :------------------------------------------------------------------ |
| `id`                   | `string` | Canonical account ID — unique identifier for this unified company   |
| `domain`               | `string` | Company website domain                                              |
| `slug`                 | `string` | Company name slugified (lowercased, suffixes stripped, dash-joined) |
| `linkedin_id`          | `string` | LinkedIn company numeric ID                                         |
| `linkedin_handle`      | `string` | LinkedIn company vanity URL slug                                    |
| `crunchbase_uuid`      | `string` | Crunchbase organization UUID                                        |
| `crunchbase_permalink` | `string` | Crunchbase organization permalink                                   |
| `twitter_handle`       | `string` | X / Twitter company handle                                          |
| `sales_navigator_id`   | `string` | LinkedIn Sales Navigator account ID                                 |
| `ids`                  | `object` | Map of source connector models to their original record IDs         |

<Note>
  Reference columns (`domain`, `linkedin_id`, etc.) are resolved by taking the highest-priority non-null value across all source records that share the same canonical ID.
</Note>

### Contact

The Contact model merges people records from all connected integrations into a single, deduplicated table. Each row represents a unique person, linked to their parent Account via `account_id`.

| Column                 | Type     | Description                                                      |
| :--------------------- | :------- | :--------------------------------------------------------------- |
| `id`                   | `string` | Canonical contact ID — unique identifier for this unified person |
| `email`                | `string` | Generic email address                                            |
| `personal_email`       | `string` | Personal email address                                           |
| `work_email`           | `string` | Work / professional email address                                |
| `linkedin_id`          | `string` | LinkedIn member numeric ID                                       |
| `linkedin_handle`      | `string` | LinkedIn member vanity URL slug                                  |
| `crunchbase_uuid`      | `string` | Crunchbase person UUID                                           |
| `crunchbase_permalink` | `string` | Crunchbase person permalink                                      |
| `twitter_handle`       | `string` | X / Twitter personal handle                                      |
| `sales_navigator_id`   | `string` | LinkedIn Sales Navigator lead ID                                 |
| `account_id`           | `string` | Foreign key to the unified Account `id`                          |
| `ids`                  | `object` | Map of source connector models to their original record IDs      |

<Note>
  The `account_id` is resolved through the parent unification mapping — if a source contact model declares a parent relationship to an account model, Cargo automatically links the unified contact to the correct unified account.
</Note>

### Account Event

The Account Event model aggregates event data from all connected integrations into a single timeline, where each event is linked to its parent Account.

| Column         | Type     | Description                                                      |
| :------------- | :------- | :--------------------------------------------------------------- |
| `id`           | `string` | Composite event ID (`<dataset_slug>__<model_slug>__<record_id>`) |
| `account_id`   | `string` | Foreign key to the unified Account `id`                          |
| `occurred_at`  | `date`   | Timestamp when the event occurred (from the source time column)  |
| `event_name`   | `string` | Name of the event, derived from the source model name            |
| `properties`   | `object` | Original column values from the source record, keyed by slug     |
| `dataset_slug` | `string` | Slug of the source database / dataset                            |
| `model_slug`   | `string` | Slug of the source model within the dataset                      |

### Contact Event

The Contact Event model aggregates event data from all connected integrations into a single timeline, where each event is linked to its parent Contact.

| Column         | Type     | Description                                                      |
| :------------- | :------- | :--------------------------------------------------------------- |
| `id`           | `string` | Composite event ID (`<dataset_slug>__<model_slug>__<record_id>`) |
| `contact_id`   | `string` | Foreign key to the unified Contact `id`                          |
| `occurred_at`  | `date`   | Timestamp when the event occurred (from the source time column)  |
| `event_name`   | `string` | Name of the event, derived from the source model name            |
| `properties`   | `object` | Original column values from the source record, keyed by slug     |
| `dataset_slug` | `string` | Slug of the source database / dataset                            |
| `model_slug`   | `string` | Slug of the source model within the dataset                      |

***

## References

References are the shared identifiers Cargo uses to match records across integrations. Each unification type supports a specific set of references. Event models inherit the references of their parent type.

### Account references

Used by the **Account** and **Account Event** models.

| Reference                | Description                                                    |
| :----------------------- | :------------------------------------------------------------- |
| **Domain**               | Company website domain (e.g. `acme.com`)                       |
| **Slug**                 | Company or billing-entity name, slugified — matching is opt-in |
| **LinkedIn ID**          | LinkedIn company numeric ID                                    |
| **LinkedIn Handle**      | LinkedIn company vanity URL slug                               |
| **Crunchbase UUID**      | Crunchbase organization UUID                                   |
| **Crunchbase Permalink** | Crunchbase organization permalink                              |
| **Twitter Handle**       | X / Twitter company handle                                     |
| **Sales Navigator ID**   | LinkedIn Sales Navigator account ID                            |

### Contact references

Used by the **Contact** and **Contact Event** models.

| Reference                | Description                       |
| :----------------------- | :-------------------------------- |
| **Email**                | Generic email address             |
| **Personal Email**       | Personal email address            |
| **Work Email**           | Work / professional email address |
| **LinkedIn ID**          | LinkedIn member numeric ID        |
| **LinkedIn Handle**      | LinkedIn member vanity URL slug   |
| **Crunchbase UUID**      | Crunchbase person UUID            |
| **Crunchbase Permalink** | Crunchbase person permalink       |
| **Twitter Handle**       | X / Twitter personal handle       |
| **Sales Navigator ID**   | LinkedIn Sales Navigator lead ID  |

***

## Slug matching

The **Slug** reference is the account's name, normalized. **Slug matching is opt-in** — it is `"none"` by default and does nothing until you enable it in the unification settings below. When enabled, the slug participates like any other weak identifier: identical normalized names corroborate a merge, but never cause one on their own. The slug reference exists on accounts only: person names need different matching semantics (a first+last+domain composite), so contacts carry no slug reference yet.

**Slugification.** Company names are lowercased, punctuation is stripped, a leading "the" is dropped, trailing legal-entity tokens (`Inc`, `LLC`, `GmbH`, `OpCo`, …) are removed, and the remaining tokens are dash-joined — so `OpenAI, Inc.` and `OpenAI OpCo LLC` both slugify to `openai`, and `The Coca-Cola Company` to `coca-cola`. Brand words like "Labs" are kept (Bell Labs is not Bell), so name variants stay distinct.

**Turning it on.** Set the slug to `"weak"` in the unification settings below. It then joins the identifier graph at the same trust level as a Twitter handle: weak identifiers never merge records on their own and can never bridge two strong components, so two accounts with different domains are never merged just because their names look alike. Placeholder slugs (`test`, `unknown`, `n-a`, …) and slugs shared by too many records are ignored entirely.

### Unification settings

How references match is configurable per unified model, through the model's extractor config — via the API (`PUT /v1/storage/models/:uuid` with `config`) or in code:

```ts models/accounts.ts theme={null}
import { defineModel } from "@cargo-ai/cdk";

export const accounts = defineModel("accounts", {
  kind: "native",
  extractSlug: "unifyAccounts",
  config: {
    domain: "strong",
    // Opt in to slug matching (identical normalized slugs only).
    slug: "weak",
    linkedinId: "strong",
    linkedinHandle: "weak",
    crunchbaseUuid: "strong",
    // Override a reference's merge trust.
    crunchbasePermalink: "strong",
    // Keep the golden column, but never merge on it.
    twitterHandle: "none",
    salesNavigatorId: "strong",
  },
});
```

The config is the complete map of reference → how it merges. There are three settings:

| Setting    | Meaning                                                                                      |
| :--------- | :------------------------------------------------------------------------------------------- |
| `"strong"` | Merges records on its own — forms the backbone of a unified entity.                          |
| `"weak"`   | Only corroborates a merge; can never bridge two records that disagree on a strong reference. |
| `"none"`   | Keeps the golden column populated, but never merges on it.                                   |

Every reference must be present. New models are seeded with the curated defaults — `domain`, `email`, and the ID-style references are `strong`, handles and permalinks are `weak`, and the `slug` is `none` (matching is opt-in). Updates must send the complete map back — read the model's current `config`, adjust the entries you want, and PUT the whole object back.

<Note>
  The highest-precision way to resolve a name-only record remains enrichment:
  resolve the name to a domain with an enrichment play, and the deterministic
  domain match takes over from there.
</Note>

***

## Reference priority

When multiple references match, Cargo uses an **ordered reference list** to determine which reference takes priority for deduplication. You can configure this order per unified model in the workspace settings.

For example, with the default account reference order `[domain, linkedinId, linkedinHandle, ...]`, two records sharing the same `domain` will be merged even if their `linkedinId` values differ.

***

## Relationships

The four unified models form a connected graph:

| Relationship            | Column       | Type        | Description                                         |
| :---------------------- | :----------- | :---------- | :-------------------------------------------------- |
| Contact → Account       | `account_id` | Many-to-one | Each contact is linked to one unified account       |
| Account Event → Account | `account_id` | Many-to-one | Each account event is linked to one unified account |
| Contact Event → Contact | `contact_id` | Many-to-one | Each contact event is linked to one unified contact |

***

## Source tracking

Every unified record includes an `ids` column — a JSON object that maps back to the original records from each contributing integration:

```json theme={null}
{
  "<dataset_slug>__<model_slug>": "<original_record_id>",
  "hubspot__companies": "12345",
  "salesforce__accounts": "001Ab00000XyZ"
}
```

For event models, the `id` itself is a composite key that encodes the source: `<dataset_slug>__<model_slug>__<original_record_id>`.

The `properties` column on event models preserves all original columns from the source record as a JSON object, so no data is lost during unification.


# Using UI
Source: https://docs.getcargo.ai/models/using-ui

Learn about data models and how they power Cargo plays

<div>
  <iframe title="Setup a data model" />
</div>

## What are data models?

Data models are structured tables that power your Cargo plays. They contain organized data that can be imported into plays to create runs.

Cargo enables you to build data models from multiple sources—API endpoints, webhook events, and SQL queries—and merge them into a unified, cohesive structure.

<Note>
  Cargo uses a data warehouse to host your data models. By default you get a
  managed BigQuery instance; you can connect your own BigQuery or Snowflake.
</Note>

***

## Where the data comes from

Cargo supports two complementary ways to populate a data model:

| Source                                     | Description                                                                                                                                        |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**Object models**](/models/object-models) | Native, writable models — `Account`, `Contact`, `Deal`, `Lead`, or fully custom — that your plays, tools, and agents insert records into directly. |
| **Native integrations**                    | Connect to supported external APIs (CRMs, enrichment tools, etc.) and fetch data directly into a data model.                                       |
| **Webhook loader**                         | Listen for real-time events from external sources and import that data automatically.                                                              |
| **SQL loader**                             | Run SQL queries on your data warehouse tables and import the results.                                                                              |

Cargo also computes [unified models](/models/unification) on top of these sources, giving you deduplicated `Account`, `Contact`, and event tables across every system you connect.

***

## Advanced features

Data models support powerful capabilities to help you orchestrate your GTM workflows:

<AccordionGroup>
  <Accordion title="System of record" icon="server">
    Cargo is the GTM system of record: store companies, contacts and deals,
    sync every GTM source, unify on one key. Built for scale — billions of
    records, SQL throughout.
  </Accordion>

  <Accordion title="Segments" icon="filter">
    Apply filters to create targeted segments for specific plays based on custom
    criteria.
  </Accordion>

  <Accordion title="Change-based triggers" icon="bolt">
    Enable plays to respond in real-time to updates, additions, or deletions in
    your data.
  </Accordion>

  <Accordion title="Enrolment conditions" icon="shield-check">
    Track processed records to prevent plays from handling the same data
    multiple times.
  </Accordion>

  <Accordion title="Data model relationships" icon="diagram-project">
    Connect different data models using common identifiers to create unified
    views of your customer data.
  </Accordion>

  <Accordion title="Additional columns" icon="table-columns">
    Extend your data models with calculated fields and custom data: - **Custom
    columns:** Free-form columns you can upsert from within a play - **Computed
    columns:** Calculated values based on other columns in the data model -
    **Metrics columns:** Aggregated data (sums, averages, counts) from related
    data models
  </Accordion>
</AccordionGroup>

***

## Use cases

Data models power a wide range of GTM scenarios:

| Use case              | Description                                                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **CRM sync**          | Import customer information, deal pipelines, and sales activities from Salesforce or HubSpot to create unified customer profiles. |
| **Intent signals**    | Capture website behavior, form submissions, and engagement metrics to identify prospects showing buying intent.                   |
| **List building**     | Aggregate contact lists from marketing campaigns, events, and lead generation activities for targeted outreach.                   |
| **Product analytics** | Query product catalogs, usage analytics, and inventory levels to inform customer interactions.                                    |

***

## Next steps

<CardGroup>
  <Card title="Build a play" icon="play" href="/plays/using-ui">
    Learn how to create automated workflows powered by your data models.
  </Card>

  <Card title="Querying data" icon="code" href="/models/querying">
    Write custom SQL queries to transform and combine your data.
  </Card>

  <Card title="System of record" icon="database" href="/integration/overview">
    Connect your own data warehouse as the backbone of your data models.
  </Card>

  <Card title="Object models" icon="cube" href="/models/object-models">
    Define writable models for accounts, contacts, deals, leads, and custom
    objects.
  </Card>

  <Card title="Explore actions" icon="bolt" href="/workflows/overview#the-action-catalog">
    Browse model search, record, custom column, and 120+ other actions.
  </Card>
</CardGroup>


# Overview
Source: https://docs.getcargo.ai/plays/overview

Event-driven automations that run a workflow over a data model as its rows change. Define them with definePlay.

A **play** runs a [workflow](/workflows/overview) over a [data model](/models/overview), emitting a run for each row that changes. Where a tool is triggered on demand, a play continuously watches its model and fires when matching changes occur. You define one with `definePlay`.

## Define a play

```ts plays/onboarding.ts theme={null}
import { definePlay, defineWorkflow } from "@cargo-ai/cdk";
import { z } from "zod";
import { contacts } from "../models/contacts";
import { enrich } from "../tools/enrich";

const onboardRow = defineWorkflow(
  "onboard-contact",
  {
    input: z.object({ email: z.string() }),
    output: z.object({ welcomed: z.boolean(), message: z.string() }),
    uses: { enrich },
  },
  ({ input, uses, ai }) => {
    const enriched = uses.enrich({ email: input.email });
    const message = ai(
      `Draft a one-line welcome for ${input.email} at ${enriched.company}.`,
    );
    return { welcomed: true, message };
  },
);

export const onboarding = definePlay("onboarding", {
  model: contacts,                    // the model whose rows drive it
  workflow: onboardRow,               // per-row automation, deployed as the release
  changeKinds: ["added", "updated"],  // which row changes fire a run
  runCreationRule: "always",
  schedule: { type: "realtime" },     // fire as rows change; see below for other types
});
```

The per-row `workflow` is deployed as the play's release. `changeKinds` and `schedule` control when runs are created. `schedule` accepts one of:

| `type`       | Fires…                                                                 |
| ------------ | ---------------------------------------------------------------------- |
| `realtime`   | as the model's rows change (the reactive default for row-driven plays) |
| `cron`       | on a cron expression — `{ type: "cron", cron: "0 * * * *" }`           |
| `dbt`        | after a dbt job completes                                              |
| `dependency` | after another play finishes — `{ type: "dependency", play: upstream }` |
| `watch`      | on a watched external schedule                                         |

<Note>
  `realtime` and `watch` are distinct: `realtime` reacts to row changes in the
  model, while `watch` follows an externally managed schedule.
</Note>

## Deploy and trigger

```bash theme={null}
cargo-ai project deploy
cargo-ai orchestration play list                 # → workflowUuid, modelUuid
cargo-ai orchestration batch create \
  --workflow-uuid <uuid> \
  --data '{"kind":"filter","modelUuid":"<uuid>"}' \
  --wait-until-finished
```

`{"kind":"filter"}` enrols every row of the model; add a `filter` to narrow it.
See [Triggering](/plays/triggering#trigger-a-batch-manually) for the other data
kinds.

<Warning>
  Plays always use `batch create`, never `run create` — `run create` on a play's
  workflow returns a `playNotCompatible` error.
</Warning>

<Warning>
  Do **not** pass the `segmentUuid` returned by `play list` to
  `{"kind":"segment"}`. That is the play's internally generated segment, whose
  record count is never populated, so the batch fails with `noRecords`.
  `{"kind":"segment"}` is for standalone segments from
  `segmentation segment list` — see [Segments](/models/segments#use-a-segment).
</Warning>

## Fallbacks and health

Add fallback paths so a failed step doesn't fail the whole run (notify, try an alternative provider, write defaults, or skip and continue). Watch success rate and set batch-health alerts. See [Triggering](/plays/triggering) for schedules and enrolment, and [Monitoring](/tools/monitoring) for records and metrics.

Batch health is declarative on the play: `healthThreshold` is the minimum percentage of successful runs (0–100) for a finished batch to count healthy, and `healthAlertActions` fire — each as its own run — when a batch lands below it. Actions take a connector action, an agent, or a tool:

```ts theme={null}
export const onboarding = definePlay("onboarding", {
  model: contacts,
  workflow: onboardRow,
  healthThreshold: 90,
  healthAlertActions: [
    {
      ref: slack.actions.postMessage,
      config: {
        channelId: "C0123456789",
        format: "markdown",
        body: "Onboarding batch unhealthy — {{batch.url}}",
      },
    },
    { ref: sentinel, config: { prompt: "Investigate the unhealthy batch" } },
  ],
});
```

Omit both fields to keep health managed from the UI; an explicit `[]` clears the actions.

These are the same action shapes an alert fires, so `config` can be type-checked the same way — wrap a connector action in [`alertConnectorAction`](/alerts/overview#actions-what-fires-on-breach) or a tool in `alertToolAction`, and an agent's is typed already. Here the interpolation roots are `play` and `batch` (`{{batch.url}}`) rather than an alert's `alert` and `event`.

## Using the UI

See [Using the UI](/plays/using-ui) for the visual play editor — publishing, manual enrolment, re-running failed runs, and fallback configuration.


# Triggering a play
Source: https://docs.getcargo.ai/plays/triggering

Declare a play's schedule, change detection, enrolment rules, and filters in code with definePlay

A play watches its [model](/models/overview) and emits a run per changed row. When and how it fires is declared on `definePlay` — schedule, which changes count, how records enrol, and which rows are eligible. All of it deploys with `cargo-ai project deploy`.

## Configure triggers in code

```ts plays/onboarding.ts theme={null}
export const onboarding = definePlay("onboarding", {
  model: contacts,
  workflow: onboardRow,
  schedule: { type: "realtime" },        // fire as rows change
  changeKinds: ["added", "updated"],     // which changes create a run
  runCreationRule: "once",               // enrol each record only once
  filter: {
    conjonction: "and",
    groups: [{
      conjonction: "and",
      conditions: [
        { kind: "string", columnSlug: "country", operator: "is", values: ["US"] },
      ],
    }],
  },
});
```

## Schedule

The `schedule` field selects how the play is driven:

| `schedule`                               | Behavior                                  |
| ---------------------------------------- | ----------------------------------------- |
| `{ type: "realtime" }`                   | Fire instantly as the model's rows change |
| `{ type: "cron", cron: "0 * * * *" }`    | Run on a cron expression (UTC)            |
| `{ type: "dependency", play: upstream }` | Run after another play finishes           |
| `{ type: "watch" }`                      | Run on a watched external schedule        |
| `{ type: "dbt", jobId: "…" }`            | Run after a dbt job completes             |

<Info>
  Real-time schedules are currently only available for **HubSpot** and
  **Salesforce**. The minimum interval for scheduled syncs depends on the model
  type (as short as 5 minutes, up to 1 day); a sync is skipped if the model was
  already refreshed within that window.
</Info>

## Change detection

`changeKinds` controls which row changes create a run. Defaults to `["added"]`.

* **Real-time** schedules know exactly what happened — a row was `added` (created in the source) or `updated`.
* **Scheduled** syncs (cron, dependency, watch) compare snapshots, so `added` means "appears in this sync but not the last" — which includes newly created rows, rows that now match the `filter` for the first time, and restored rows.

## Enrolment rules

`runCreationRule` controls what happens when a record triggers repeatedly:

| Value             | UI equivalent                | Behavior                                             |
| ----------------- | ---------------------------- | ---------------------------------------------------- |
| `"always"`        | Always enrol                 | New run every time the trigger fires for that record |
| `"once"`          | Enrol once                   | Each record is enrolled at most once, ever           |
| `"noConcurrency"` | If is not currently enrolled | Skip if the record is already in an active run       |

<Warning>
  **Feedback loops with `"always"` + real-time on `updated`:** if the play
  writes back to the source system (e.g. updating a HubSpot field), that write
  is itself an update event that re-triggers the play on the same record — a
  loop that can multiply executions by orders of magnitude. Prevent it with
  `runCreationRule: "once"` (or `"noConcurrency"`), by restricting
  `changeKinds` to `["added"]`, or by adding a `filter` that excludes
  already-processed rows (e.g. "score is unknown").
</Warning>

## Eligibility filter

`filter` (and optional `sort`, `limit`) restricts which rows are eligible. It uses the same JSON schema as the UI segment builder and the `segment download` CLI command.

<Warning>
  For real-time schedules, SQL, segment, occurrence, and related-model
  conditions are not supported, and neither is OR within groups / AND across
  multiple groups.
</Warning>

## Trigger a batch manually

Beyond the schedule, run a play on demand with the CLI:

```bash theme={null}
cargo-ai orchestration play list                 # → workflowUuid, modelUuid
cargo-ai orchestration batch create \
  --workflow-uuid <uuid> \
  --data '{"kind":"filter","modelUuid":"<uuid>"}' \
  --wait-until-finished
```

`--data` selects which records to enrol. For a play, the useful kinds are:

| `kind`      | Payload                                   | Enrols                                                                |
| ----------- | ----------------------------------------- | --------------------------------------------------------------------- |
| `filter`    | `modelUuid`, `filter?`, `sort?`, `limit?` | Rows of the model matching the filter — omit `filter` for all of them |
| `recordIds` | `modelUuid`, `ids`                        | An explicit list of record ids                                        |
| `segment`   | `segmentUuid`                             | Every record in a standalone segment                                  |
| `runs`      | `filter`, `reset`                         | Existing runs, re-run from a chosen node                              |

<Warning>
  `{"kind":"segment"}` expects a standalone segment from
  `segmentation segment list`, **not** the `segmentUuid` that `play list`
  returns. The latter is the play's internally generated segment; its record
  count is never populated, so the batch fails with `noRecords`. Use
  `{"kind":"filter"}` with the play's `modelUuid` instead.
</Warning>

<Note>
  `{"kind":"file"}` is rejected for plays — it is only valid on tool and
  standalone workflows.
</Note>

## Health monitoring

Set a **batch health threshold** (percent of runs that must succeed) and a Slack **health alert** for when a batch drops below it. See [Monitoring](/tools/monitoring) for querying runs and metrics from the CLI.


# Using UI
Source: https://docs.getcargo.ai/plays/using-ui

Learn what plays are, how they differ from tools, and how to build your first one.

<iframe title="Build a play in Cargo" />

## What are plays?

Plays are automated workflows in Cargo that **consume data from a Cargo data model** to **programmatically trigger at the right moment** in order to execute a pre-defined workflow logic.

Plays let you build workflow logic using **actions** and **tools** and run automatically whenever a relevant change is observed in the connected data model:

* **Actions:** Cargo plays give you the ability to add custom logic that is triggered when the right changes are observed in the connected data model.
* **Data:** GTM teams rely on data from many sources—CRMs, enrichment tools, product usage, and more. Cargo data models are able to unify this data, so you can trigger plays based on the most relevant changes in that data.
* **Syncs:** Plays can process records in batches on a schedule you define, letting you control how often the play checks for new data and how many records to process at once.

> Unlike tools which are manually triggered or called by other components, plays are automatically triggered by changes in your data models.

## Use cases

Here are some of the most popular ways Cargo customers use Plays:

* **Warm outbound:** Automatically reach out to prospects at companies showing intent signals, with personalized messaging at just the right moment.
* **Champions tracking:** Monitor champions of your product and engage them when they move to new companies or roles.
* **Stakeholder research:** Turn a list of companies into high-relevance leads by finding new contacts in relevant roles to engage with.
* **Automated Lead Routing:** Instantly assign leads to the right reps based on territory, fit, or engagement signals.
* **CRM operations:** Detect errant data in your CRM systems, whether it be invalid emails or duplicate records, and trigger a custom workflow logic to remedy it.

***

## Step-by-step: Build your first play

Follow these steps to create a play that automatically processes leads when they match specific criteria.

### Step 1: Create a new play

1. Navigate to **Plays** in your Cargo workspace sidebar
2. Click **+ New Play** in the top right corner
3. Give your play a descriptive name (e.g., "New Lead Qualification")
4. You'll be taken to the play editor canvas

### Step 2: Connect a data model

Every play needs a data source to monitor. Configure your trigger:

1. Click on the **Start** node to open the trigger settings
2. Select a data model from your workspace (e.g., your CRM leads model)
3. Choose which events should trigger the play (new records, updates, or deletions)

<Tip>
  Start with a focused data model. You can always expand the trigger conditions
  later once you've validated the workflow.
</Tip>

### Step 3: Configure sync settings

Define when and how your play should process data:

1. Open the **Sync** settings panel
2. Choose your sync schedule (real-time, interval, or cron-based)
3. Set your batch size to control how many records are processed at once
4. Configure re-enrollment rules based on your use case

### Step 4: Build your workflow logic

Add nodes to define what happens when the play triggers:

1. Click **+** to add your first action node
2. For a lead qualification play, you might add:
   * An **Enrich** node to gather additional company data
   * A **Branch** node to filter leads based on criteria
   * A **Write** node to update your CRM with qualification status

### Step 5: Handle edge cases

Add fallback logic for when things go wrong:

1. Right-click on any node and select **Failure**
2. Connect a fallback path for error handling
3. Add notification nodes to alert your team of issues

### Step 6: Test with manual enrolment

Before going live, validate your play with real data:

1. Navigate to the **Records** view
2. Click the import button to manually enroll test records
3. Monitor the execution flow and verify each node's output
4. Fix any issues before enabling automatic processing

### Step 7: Publish and enable

Once everything works:

1. Click **Publish** in the top right corner
2. Toggle the **Enabled** switch to activate automatic triggers
3. Your play will now process records whenever changes are detected

***

## Best practices

* **Start with manual testing** — Always test with manual enrolments before enabling automatic triggers to validate your workflow.
* **Set appropriate re-enrollment rules** — Choose the right trigger conditions—use "No Re-Enrollment" for one-time actions, "Always Enroll" for repeated processing.
* **Monitor play health** — Set up Slack notifications when error thresholds are hit to catch issues early.
* **Use fallback paths** — Add failure handlers to gracefully manage errors and prevent silent failures.

***

## Next steps

<CardGroup>
  <Card title="Configure sync settings" icon="clock" href="/plays/triggering">
    Learn about schedules, batch sizes, and trigger conditions.
  </Card>

  <Card title="Explore actions" icon="bolt" href="/workflows/overview#the-action-catalog">
    Browse the actions you can use in a play — model search, records, memory,
    and 120+ more.
  </Card>

  <Card title="Build a tool" icon="wrench" href="/tools/using-ui">
    Create reusable tools that your plays can leverage.
  </Card>

  <Card title="Allocate leads" icon="users" href="/territories/overview">
    Route leads to the right team members automatically.
  </Card>
</CardGroup>


# Chrome Extension overview
Source: https://docs.getcargo.ai/reference/chrome-extension

Access Cargo agents and tools directly from your browser—inside your CRM, on any webpage, or anywhere you work.

The Cargo Chrome extension brings your AI-powered workflows to wherever you work. Run agents, execute tools, and enrich data without leaving your browser.

***

## What the extension does

The Chrome extension integrates Cargo directly into your daily workflow:

| Capability            | Description                                                                           |
| :-------------------- | :------------------------------------------------------------------------------------ |
| **Page analysis**     | Analyze the current webpage with your agents—extract insights, summarize, or research |
| **Quick access**      | Launch agents and tools from any browser tab                                          |
| **Context awareness** | Automatically pull context from CRM records or page content                           |

***

## Installation

1. Visit the [Chrome Web Store](https://chromewebstore.google.com/detail/cargo/gfgbpfecclegmmogcfonjpcicjhlelkb)
2. Click **Add to Chrome**
3. Sign in with your Cargo workspace credentials
4. Pin the extension to your toolbar for quick access

<Tip>
  After installation, click the Cargo icon in your toolbar and sign in to
  connect the extension to your workspace.
</Tip>

***

## Using the extension

### Inside your CRM

When viewing a contact, company, or deal in HubSpot or Salesforce, the extension adds a Cargo sidebar:

1. Navigate to a record in your CRM
2. Click the Cargo icon in your browser toolbar (or use the sidebar if enabled)
3. Choose an agent to run—the extension automatically pulls context from the page (CRM record details, visible data) and passes it to the agent
4. View results in the sidebar and let them sync back to your CRM

**Example workflow:**

* View a company in HubSpot
* Click the Cargo icon
* Run "Enrich & Score Lead"
* See results in the sidebar

<Note>
  The extension reads data from your CRM page to provide context. No additional
  CRM permissions are required beyond what Cargo already has.
</Note>

### On any webpage

Analyze any webpage with your Cargo agents:

1. Navigate to any webpage (company website, LinkedIn profile, news article)
2. Click the Cargo icon in your toolbar
3. Select an agent
4. The agent can read and analyze the current page content
5. Ask questions or run workflows based on what's on the page

**Use cases:**

* Research a prospect's company website before a call
* Summarize a news article about a target account
* Extract contact information from a LinkedIn profile
* Analyze competitor pricing pages

### Quick actions

Access your most-used tools instantly:

1. Click the Cargo icon from any tab
2. See your pinned agents and tools
3. Run with one click—enter inputs manually if needed
4. View results directly in the extension popup

***

## Configuring the extension

### Available agents

By default, the Chrome extension gives you access to:

* **Master Agent** — A general-purpose agent built by Cargo, ready to use out of the box
* **All workspace agents** — Every agent you've deployed in your Cargo workspace

### Customizing available agents

You can control which agents appear in the Chrome extension:

1. Open Cargo and navigate to **Settings**
2. Select **Cargo for Chrome**
3. In the **Available agents** section, enable or disable specific agents
4. Save your changes

This lets you curate the agent list for your team—hide agents that aren't relevant for browser-based work, or keep the list focused on your most-used workflows.

### Selecting a default agent

You can also choose which agent opens by default when you launch the extension:

1. In **Settings → Cargo for Chrome**, find the **Default agent** dropdown
2. Choose your preferred agent
3. Save your changes

The selected agent will automatically load whenever you open the extension, saving you a click on every use.

<Tip>
  Set your most-used agent as the default. You can always switch to a different
  agent from the extension's agent selector.
</Tip>

***

## Best practices

<AccordionGroup>
  <Accordion title="Set a default agent for faster access">
    Configure your most-used agent as the default in **Settings → Cargo for
    Chrome**. This loads your preferred agent instantly when you open the
    extension.
  </Accordion>

  <Accordion title="Curate your agent list">
    Disable agents you don't need in the extension settings. A focused list
    makes it faster to find the right agent for browser-based work.
  </Accordion>

  <Accordion title="Use page context effectively">
    Your agent can read the current page content. Be specific in your
    prompts—ask "What does this company do?" or "Summarize the key points on
    this page" to get targeted results.
  </Accordion>

  <Accordion title="Leverage CRM context">
    When viewing a CRM record, the extension automatically pulls in record
    details. Use this to run enrichment, qualification, or research without
    re-entering data.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup>
  <Card title="Embed tools in CRM" icon="puzzle-piece" href="/tools/embed-in-crm">
    Configure CRM buttons for one-click tool execution.
  </Card>

  <Card title="Deploy agents" icon="robot" href="/agents/overview">
    Learn how to build and deploy agents for use in the extension.
  </Card>

  <Card title="HubSpot integration" icon="hubspot" href="/integration/hubspot">
    Set up your HubSpot connection for seamless CRM integration.
  </Card>

  <Card title="Salesforce integration" icon="salesforce" href="/integration/salesforce">
    Configure Salesforce to work with the Chrome extension.
  </Card>
</CardGroup>


# Purchase Cargo credits
Source: https://docs.getcargo.ai/reference/credits

Purchase credits for all enrichment, orchestration and storage actions on Cargo

Cargo uses a flexible usage-based system, paid for with Cargo credits, which covers everything you do in the platform.

You decide how many credits you need based on your business requirements. All plans include access to every feature, no matter your usage level.

## Subscription plan types

**Self-serve plan** (default) are meant for getting started and understanding how the platform works.

**Plan-based workspaces** are more economical for higher, regular usage. These workspaces come with monthly or annual credit allocations that reset at the end of each term.

**Credits are consumed for:**

| Action                  | Cost                       | Description                                                    |
| ----------------------- | -------------------------- | -------------------------------------------------------------- |
| **Integration tasks**   | Listed per integration     | Researching companies, finding contacts, data enrichment, etc. |
| **Orchestration steps** | 1 credit per 100 steps     | Running Plays, Tools and Agents                                |
| **Storage records**     | 1 credit per 1,000 upserts | Storing and retrieving data in Cargo data models               |

## Retrieve exact costs and usage from the CLI

Everything on this page is inspectable programmatically, which also means
your AI agents can read it. The workspace UI shows per-model and per-action
costs in each action's configuration, and the CLI returns the same data as
JSON:

```bash theme={null}
# Exact credit costs, models, and schemas for any integration
cargo-ai connection integration get anthropic
cargo-ai connection integration get openAi
cargo-ai connection integration get gemini

# Your workspace's consumption and plan
cargo-ai billing usage
cargo-ai billing subscription
```

Per-integration costs (including per-model, per-1,000-token rates for AI
providers) evolve with each provider's lineup, so the CLI and the action's
model dropdown are always the authoritative source. The same reads exist in
the [API reference](/api-reference/billing--usage/get-usage-metrics) for
building your own reporting.

## Credit management

<img alt="image.png" />

### Credit reset and top-ups

Credits reset at the end of each term (monthly or annually). If you run out of credits before the end of your term, you have 3 options:

1. **Upgrade your plan** - Move to a different plan tier with more included credits. If you are on an Enterprise plan, this requires speaking to someone in the Cargo team
2. **Enable auto-topup** - Automatically purchase additional credits when needed. Credits are available for 1 year at the same rate as your current plan
3. **Request a one-time credit purchase** - Contact support to purchase additional credits. We will generate a new invoice with the amount of credits needed. Credits are available for 1 year at the same rate as your current plan

### Credits overage

<Note>Credits overage is only available for Enterprise customers.</Note>

Enterprise customers can enable credits overage to ensure uninterrupted operations. When overage is enabled:

* **Continued usage beyond allocation** - Your workflows continue running even after your credit balance reaches zero
* **Automatic invoicing** - Overage charges are tracked and invoiced automatically every month
* **Same credit rates** - Overage credits are charged at the same rates as your plan credits

For more details on calculating the right credit requirements for your needs, visit the [Cargo pricing page](https://www.getcargo.ai/pricing).


# Expression cheat sheet
Source: https://docs.getcargo.ai/reference/expressions-cheatsheet

Essential JavaScript methods for using in your Cargo expressions

Cargo uses JavaScript expressions to manipulate data within workflows. This cheat sheet covers the most commonly used methods for working with strings, arrays, and data transformations.

<Tip>
  All expressions must be wrapped in double curly brackets: `{{ expression }}`
</Tip>

## Quick reference

<CardGroup>
  <Card title="Strings" icon="font" href="#string-methods" />

  <Card title="Arrays" icon="list" href="#array-methods" />

  <Card title="Utilities" icon="wrench" href="#common-patterns" />
</CardGroup>

***

## String methods

<AccordionGroup>
  <Accordion title="split" icon="scissors">
    Split a string by a delimiter to extract specific parts.

    **Example**: Extract domain from email address

    | Input  | `nodes.start.email = "john.smith@acme-corp.com"` |
    | ------ | ------------------------------------------------ |
    | Output | `"acme-corp.com"`                                |

    ```javascript theme={null}
    {{ nodes.start.email.split("@")[1] }}
    ```
  </Accordion>

  <Accordion title="toLowerCase" icon="arrow-down">
    Convert a string to lowercase for consistent formatting.

    **Example**: Standardize company name

    | Input  | `nodes.start.companyName = "ACME Corporation"` |
    | ------ | ---------------------------------------------- |
    | Output | `"acme corporation"`                           |

    ```javascript theme={null}
    {{ nodes.start.companyName.toLowerCase() }}
    ```
  </Accordion>

  <Accordion title="toUpperCase" icon="arrow-up">
    Convert a string to uppercase.

    **Example**: Format country code

    | Input  | `nodes.start.country = "us"` |
    | ------ | ---------------------------- |
    | Output | `"US"`                       |

    ```javascript theme={null}
    {{ nodes.start.country.toUpperCase() }}
    ```
  </Accordion>

  <Accordion title="trim" icon="eraser">
    Remove whitespace from both ends of a string.

    **Example**: Clean user input

    | Input  | `nodes.start.name = "  John Smith  "` |
    | ------ | ------------------------------------- |
    | Output | `"John Smith"`                        |

    ```javascript theme={null}
    {{ nodes.start.name.trim() }}
    ```
  </Accordion>

  <Accordion title="replace" icon="repeat">
    Replace part of a string with another value.

    **Example**: Anonymize email domain

    | Input  | `nodes.start.email = "john@competitor.com"` |
    | ------ | ------------------------------------------- |
    | Output | `"john@[redacted].com"`                     |

    ```javascript theme={null}
    {{ nodes.start.email.replace("competitor", "[redacted]") }}
    ```

    <Info>
      Use `replaceAll()` to replace all occurrences, not just the first one.
    </Info>
  </Accordion>
</AccordionGroup>

***

## Array methods

<AccordionGroup>
  <Accordion title="length" icon="ruler-horizontal">
    Count how many items are present in an array.

    **Example**: Count the number of stakeholders found

    | Input  | `nodes.array = ["John Smith", "Sarah Johnson", "Mike Davis", "Lisa Chen"]` |
    | ------ | -------------------------------------------------------------------------- |
    | Output | `4`                                                                        |

    ```javascript theme={null}
    {{ nodes.array.length }}
    ```
  </Accordion>

  <Accordion title="includes" icon="magnifying-glass">
    Check if a value exists in an array.

    **Example**: Check if the product is in an allowed list

    | Input   | `nodes.start.product = "posters"`            |
    | ------- | -------------------------------------------- |
    | Allowed | `["posters", "calendars", "books", "cards"]` |
    | Output  | `true`                                       |

    ```javascript theme={null}
    {{ ["posters", "calendars", "books", "cards"].includes(nodes.start.product) }}
    ```
  </Accordion>

  <Accordion title="slice" icon="scissors">
    Extract a portion of an array.

    **Example**: Limit stakeholders to first 5

    | Input  | `nodes.apollo.stakeholders = ["John", "Sarah", "Mike", "Lisa", "David", "Emma", "Tom"]` |
    | ------ | --------------------------------------------------------------------------------------- |
    | Output | `["John", "Sarah", "Mike", "Lisa", "David"]`                                            |

    ```javascript theme={null}
    {{ nodes.apollo.stakeholders.slice(0, 5) }}
    ```

    <Info>
      `slice(start, end)` extracts elements from index `start` up to (but not including) `end`.
    </Info>
  </Accordion>

  <Accordion title="filter" icon="filter">
    Create a new array based on a condition.

    **Example**: Filter case study URLs

    | Input  | `["https://example.com/case-studies/tech", "https://example.com/blog", "https://example.com/case-studies/finance"]` |
    | ------ | ------------------------------------------------------------------------------------------------------------------- |
    | Output | `["https://example.com/case-studies/tech", "https://example.com/case-studies/finance"]`                             |

    ```javascript theme={null}
    {{ nodes.start.urls.filter((url) => url.includes("/case-studies/")) }}
    ```
  </Accordion>

  <Accordion title="join" icon="link">
    Convert an array to a string with a delimiter.

    **Example**: Convert countries to comma-separated string

    | Input  | `nodes.start.countries = ["US", "CA", "UK", "DE"]` |
    | ------ | -------------------------------------------------- |
    | Output | `"US, CA, UK, DE"`                                 |

    ```javascript theme={null}
    {{ nodes.start.countries.join(", ") }}
    ```
  </Accordion>

  <Accordion title="map" icon="arrows-rotate">
    Transform each element in an array.

    **Example**: Add company data to stakeholders

    <Tabs>
      <Tab title="Input">
        ```json theme={null}
        // nodes.apollo.stakeholders
        [
          { "name": "John", "title": "CEO" },
          { "name": "Sarah", "title": "CTO" }
        ]

        // nodes.start.domain = "acme.com"
        // nodes.hubspot.companyId = "12345"

        ```
      </Tab>

      <Tab title="Output">
        ```json theme={null}
        [
          { "name": "John", "title": "CEO", "domain": "acme.com", "hubspotId": "12345" },
          { "name": "Sarah", "title": "CTO", "domain": "acme.com", "hubspotId": "12345" }
        ]
        ```
      </Tab>
    </Tabs>

    ```javascript theme={null}
    {{
      nodes.apollo.stakeholders.map((stakeholder) => ({
        ...stakeholder,
        domain: nodes.start.domain,
        hubspotId: nodes.hubspot.companyId,
      }))
    }}
    ```
  </Accordion>

  <Accordion title="find" icon="crosshairs">
    Return the first element that matches a condition.

    **Example**: Find the CEO in a stakeholders list

    | Input  | `[{ "name": "John", "title": "CEO" }, { "name": "Sarah", "title": "CTO" }]` |
    | ------ | --------------------------------------------------------------------------- |
    | Output | `{ "name": "John", "title": "CEO" }`                                        |

    ```javascript theme={null}
    {{ nodes.apollo.stakeholders.find((s) => s.title === "CEO") }}
    ```

    <Info>
      Returns `undefined` if no element matches. Use optional chaining (`?.`) to safely access properties.
    </Info>
  </Accordion>

  <Accordion title="concat" icon="object-group">
    Merge two arrays together.

    **Example**: Combine prospect lists

    | Input  | `nodes.start.countries1 = ["US", "CA"]` and `nodes.start.countries2 = ["UK", "DE"]` |
    | ------ | ----------------------------------------------------------------------------------- |
    | Output | `["US", "CA", "UK", "DE"]`                                                          |

    ```javascript theme={null}
    {{ nodes.start.countries1.concat(nodes.start.countries2) }}
    ```
  </Accordion>
</AccordionGroup>

***

## Date and time

<AccordionGroup>
  <Accordion title="new Date()" icon="calendar">
    Create a timestamp.

    **Example**: Get current timestamp

    | Output | `"2024-01-15T10:30:45.123Z"` |
    | ------ | ---------------------------- |

    ```javascript theme={null}
    {{ new Date() }}
    ```
  </Accordion>

  <Accordion title="toLocaleDateString()" icon="calendar-day">
    Format date in localized format.

    **Example**: Format current date

    | Output | `"1/15/2024"` |
    | ------ | ------------- |

    ```javascript theme={null}
    {{ new Date().toLocaleDateString() }}
    ```

    <Info>
      Pass a locale string for different formats: `toLocaleDateString('en-GB')` returns `"15/01/2024"`
    </Info>
  </Accordion>
</AccordionGroup>

***

## Mathematical operations

<Accordion title="Basic arithmetic" icon="calculator">
  Perform calculations on numbers.

  **Example**: Calculate win rate

  | Input  | `nodes.start.wins = 15`, `nodes.start.total = 50` |
  | ------ | ------------------------------------------------- |
  | Output | `30`                                              |

  ```javascript theme={null}
  // Add to balance
  {{ nodes.start.balance + 100 }}

  // Calculate percentage
  {{ (nodes.start.wins / nodes.start.total) * 100 }}
  ```

  Other common operations:

  ```javascript theme={null}
  // Round to 2 decimal places
  {{ Math.round(nodes.start.value * 100) / 100 }}

  // Get the maximum value
  {{ Math.max(nodes.start.a, nodes.start.b) }}

  // Get the minimum value
  {{ Math.min(nodes.start.a, nodes.start.b) }}
  ```
</Accordion>

***

## Common patterns

<AccordionGroup>
  <Accordion title="Conditional logic" icon="code-branch">
    Use ternary operators for simple conditions.

    **Example**: Set priority based on score

    | Input  | `nodes.start.score = 85` |
    | ------ | ------------------------ |
    | Output | `"High Priority"`        |

    ```javascript theme={null}
    {{ nodes.start.score > 80 ? "High Priority" : "Standard" }}
    ```

    **Nested conditions**:

    ```javascript theme={null}
    {{ nodes.start.score > 80 ? "High" : nodes.start.score > 50 ? "Medium" : "Low" }}
    ```
  </Accordion>

  <Accordion title="Object property access" icon="sitemap">
    Access nested properties using dot notation.

    **Example**: Extract the city from a nested address

    <Tabs>
      <Tab title="Input">
        ```json theme={null}
        // nodes.start
        {
          "user": {
            "address": {
              "city": "San Francisco"
            }
          }
        }
        ```
      </Tab>

      <Tab title="Output">
        ```
        "San Francisco"
        ```
      </Tab>
    </Tabs>

    ```javascript theme={null}
    {{ nodes.start.user.address.city }}
    ```
  </Accordion>

  <Accordion title="Null checking" icon="shield-halved">
    Safely access properties that might not exist using optional chaining.

    **Example**: Get theme with default fallback

    <Tabs>
      <Tab title="Input">
        ```json theme={null}
        // nodes.start
        {
          "user": {
            "preferences": null
          }
        }
        ```
      </Tab>

      <Tab title="Output">
        ```
        undefined  // (safe, no error thrown)
        ```
      </Tab>
    </Tabs>

    ```javascript theme={null}
    // Safely access optional property
    {{ nodes.start.user?.preferences?.theme }}

    // With default fallback
    {{ nodes.start.user?.preferences?.theme ?? "default" }}
    ```

    <Warning>
      Without `?.`, accessing `preferences.theme` when `preferences` is `null` would throw an error.
    </Warning>
  </Accordion>

  <Accordion title="Default values" icon="rotate-left">
    Provide fallback values when data might be missing.

    **Example**: Use a default name when none is provided

    | Input  | `nodes.start.name = undefined` |
    | ------ | ------------------------------ |
    | Output | `"Anonymous"`                  |

    ```javascript theme={null}
    // Using nullish coalescing
    {{ nodes.start.name ?? "Anonymous" }}

    // Using logical OR (also catches empty strings)
    {{ nodes.start.name || "Anonymous" }}
    ```
  </Accordion>
</AccordionGroup>

***

## Tips & best practices

* **Use autocomplete** — Access the autocomplete feature while writing expressions by pressing `/` on your keyboard.
* **Node connections matter** — You cannot use a node's outputs in an expression when the node isn't connected to prior nodes in the execution logic.
* **Zero-indexed arrays** — Arrays in JavaScript are zero-indexed. The first element is at index `0`, not `1`.
* **Chain methods** — You can chain multiple methods together: `{{ nodes.start.email.split('@')[1].toLowerCase() }}`


# Glossary
Source: https://docs.getcargo.ai/reference/glossary

Definitions of key terms and concepts used throughout Cargo

Quick reference for the terminology you'll encounter when building with Cargo.

***

## Core concepts

<AccordionGroup>
  <Accordion title="Tool" icon="wrench">
    **Modular, reusable automation workflows that you build once and deploy anywhere.**

    Tools are the building blocks of Cargo—single-purpose automations for enrichment, scoring, CRM updates, or any custom logic. You can use tools standalone, chain them in plays, invoke them from agents, or expose them via API.

    **Example:** A tool that takes a company domain as input, enriches it with firmographic data, and returns a qualification score.

    [Learn more →](/tools/overview)
  </Accordion>

  <Accordion title="Play" icon="diagram-project">
    **Automated workflows that trigger based on changes in your data models.**

    Unlike tools which are manually triggered, plays continuously monitor your data and execute when relevant changes occur. Plays orchestrate tools, agents, and actions into multi-step processes that run on autopilot.

    **Example:** A play that triggers when a new lead is added to your CRM, enriches their data, scores them, and routes them to the appropriate sales rep.

    [Learn more →](/plays/overview)
  </Accordion>

  <Accordion title="Agent" icon="robot">
    **AI-powered autonomous workers that plan and execute multi-step tasks using reasoning.**

    Unlike plays that follow predetermined paths, agents use large language models (LLMs) to dynamically determine the best approach based on context. They can call tools, search data, and make decisions when tasks require adaptability.

    **Example:** An agent that researches a prospect by browsing their website, finding relevant news, and synthesizing a personalized outreach angle.

    [Learn more →](/agents/overview)
  </Accordion>

  <Accordion title="Node" icon="circle">
    **An individual step in a tool or play workflow.**

    Nodes are the building blocks you connect together on the visual canvas. Each node performs a specific action—enriching data, branching logic, writing to a CRM, or calling an API. Data flows from one node to the next via connections.

    **Example:** An "Enrich Company" node that takes a domain and returns firmographic data, followed by a "Branch" node that routes based on company size.

    [Learn more →](/workflows/overview)
  </Accordion>

  <Accordion title="Action" icon="bolt">
    **Operations that make things happen in Cargo.**

    Actions are the individual capabilities you can add to tools and plays—enrichment calls, CRM writes, AI prompts, logic branches, and more. Cargo offers 120+ actions across categories like Logic, AI, Sales, Storage, and Integrations.

    **Example:** A "HubSpot Upsert" action that creates or updates a contact, or a "Model Ask" action that queries an LLM.

    [Learn more →](/workflows/overview#the-action-catalog)
  </Accordion>

  <Accordion title="Resource" icon="layer-group">
    **Data foundations that power your Cargo workspace.**

    Resources connect your tools, agents, and plays to the information they need. This includes structured data models, unstructured files (documents, PDFs), and your data warehouse connection.

    **Example:** A "Product Knowledge Base" file resource that agents can search to answer customer questions accurately.

    [Learn more →](/models/overview)
  </Accordion>

  <Accordion title="Data Model" icon="table">
    **Structured tables that power your plays and workflows.**

    Data models contain organized data imported from CRMs, APIs, webhooks, or SQL queries. They serve as the foundation for triggering plays and storing results. Data models live in your data warehouse (managed or self-hosted).

    **Example:** A "Leads" data model that syncs contacts from HubSpot and tracks which ones have been processed by your qualification play.

    [Learn more →](/models/overview)
  </Accordion>

  <Accordion title="Object Model" icon="cube">
    **A native, writable data model owned by your Cargo workspace.**

    Object models hold records that Cargo itself produces — sourced leads, internal pipelines, agent outputs, or any custom entity that doesn't live in an external system. Cargo ships built-in `Account`, `Contact`, `Deal`, and `Lead` schemas, plus a `Custom` type where you define your own columns. Plays, tools, and agents insert, update, upsert, and remove records directly.

    **Example:** A "Sourced Leads" object model that an agent populates from research, then converts into unified Account / Contact records once qualified.

    [Learn more →](/models/object-models)
  </Accordion>

  <Accordion title="Unified Model" icon="diagram-project">
    **Read-only data models that deduplicate records across all your sources.**

    Cargo continuously merges records from every connected integration and object model into four canonical tables — `Account`, `Contact`, `Account Event`, and `Contact Event` — using shared identifiers like `domain`, `email`, or `linkedin_id`. Use unified models when you want one row per real-world entity instead of one row per source.

    **Example:** A single unified `Account` row for `acme.com` that combines its HubSpot company, Salesforce account, and Clearbit enrichment.

    [Learn more →](/models/unification)
  </Accordion>

  <Accordion title="Workspace" icon="grid-2">
    **Your Cargo environment where you build and manage automations.**

    A workspace contains your tools, plays, agents, models, and integrations. Team members collaborate within a shared workspace, and all automations run against the same connected data sources.
  </Accordion>

  <Accordion title="Mailbox" icon="envelope">
    **An inbox Cargo owns and sends from, on a sending domain the workspace registered.**

    Mailboxes are declared with `defineMailbox` on a `defineDomain` domain (`jane@acme-outreach.com`), warmed, and paced so cold outreach does not burn reputation. You send with the native `sendEmail` action from a play or tool — there is no HTTP send route. Until warm-up is started the daily ceiling stays at 5 real sends per rolling 24 hours.

    **Example:** A Google mailbox `jane@acme-outreach.com` used by an outreach play to introduce new contacts.

    [Learn more →](/mailboxes/overview)
  </Accordion>

  <Accordion title="Sending domain" icon="globe">
    **A domain registered through Cargo that mailboxes are created on.**

    You declare one with `defineDomain` (or buy it under Settings → Domains). A mailbox (`defineMailbox`) can only be provisioned once the domain is active. Registration charges credits and is not refundable.

    [Learn more →](/mailboxes/overview#register-a-sending-domain)
  </Accordion>
</AccordionGroup>

***

## Workflow concepts

<AccordionGroup>
  <Accordion title="Trigger" icon="bolt">
    **The condition that starts a play execution.**

    Triggers define when a play runs and what data it receives. Common triggers include scheduled intervals, data changes (new records, updated fields), and manual enrolment.

    [Learn more →](/plays/triggering)
  </Accordion>

  <Accordion title="Run" icon="play">
    **A single execution of a play for one record.**

    When a play triggers, it creates a run for each matching record. Runs track the execution status, node outputs, and any errors. You can monitor, retry, or re-run failed runs.
  </Accordion>

  <Accordion title="Enrolment" icon="user-plus">
    **The process of adding records to a play for processing.**

    Records can be enrolled automatically (when trigger conditions are met) or manually (by importing specific records). Enrolment conditions prevent the same record from being processed multiple times.

    [Learn more →](/plays/triggering)
  </Accordion>

  <Accordion title="Connection" icon="arrow-right">
    **The link between two nodes that defines data flow.**

    Connections determine the execution order and how outputs from one node become inputs to the next. Branch and Switch nodes have multiple output connections for different paths.
  </Accordion>

  <Accordion title="Fallback" icon="shield">
    **An alternative path that executes when a node fails.**

    Fallbacks let you handle errors gracefully—sending notifications, trying alternative providers, or writing default values instead of letting the entire run fail.

    [Learn more →](/plays/overview#fallbacks-and-health)
  </Accordion>

  <Accordion title="Expression" icon="code">
    **A reference to data from previous nodes.**

    Expressions use double curly braces to access outputs: `{{nodes.start.company_domain}}`, `{{nodes.enrich_company.name}}`. They let you map data between nodes dynamically.

    [Learn more →](/reference/expressions-cheatsheet)
  </Accordion>
</AccordionGroup>

***

## Resource concepts

<AccordionGroup>
  <Accordion title="Warehouse" icon="database">
    **The data infrastructure that hosts your data models.**

    Cargo uses a data warehouse (BigQuery, Snowflake) as the backbone for storing and querying your data models. You can use Cargo's managed BigQuery instance or connect your own warehouse.

    [Learn more →](/integration/overview)
  </Accordion>

  <Accordion title="Segment" icon="filter">
    **A filtered subset of a data model's records.**

    Segments let you create targeted groups for specific plays based on criteria like industry, company size, or lead score. Different plays can operate on different segments of the same data model.
  </Accordion>

  <Accordion title="Custom column" icon="table-columns">
    **A user-defined field you can write to from plays.**

    Custom columns extend your data models with data generated by your workflows—enrichment results, scores, processing timestamps, or any other values your plays produce.
  </Accordion>

  <Accordion title="RAG (Retrieval-Augmented Generation)" icon="magnifying-glass">
    **A technique that gives agents access to your data when reasoning.**

    RAG allows agents to search your data models and files to find relevant context before generating responses. This grounds the agent's output in your actual business data.

    [Learn more →](/agents/resources-and-context)
  </Accordion>
</AccordionGroup>

***

## Deployment concepts

<AccordionGroup>
  <Accordion title="Draft" icon="pencil">
    **An unpublished version of a tool or play.**

    Changes are automatically saved as drafts while you work. Draft changes don't affect live executions until you publish them.
  </Accordion>

  <Accordion title="Publish" icon="rocket">
    **Making a tool or play version active.**

    Publishing creates a new version that will be used for all future executions. Previously running plays continue using their configured version until updated.
  </Accordion>

  <Accordion title="MCP (Model Context Protocol)" icon="plug">
    **A protocol for exposing Cargo tools to external AI systems.**

    MCP lets you use your Cargo tools from AI assistants like Claude, Cursor, or other MCP-compatible clients. Your tools become callable functions in any MCP environment.
  </Accordion>

  <Accordion title="Revenue Organization" icon="users">
    **Specialized routing and territory management features.**

    Revenue organization includes lead allocation rules, territory definitions, and workload distribution—automating how leads get assigned to the right sales reps.

    [Learn more →](/territories/overview)
  </Accordion>
</AccordionGroup>

***

## Quick reference

| Term              | One-line definition                                    |
| :---------------- | :----------------------------------------------------- |
| **Play**          | Event-driven workflow that runs when data changes      |
| **Tool**          | Reusable automation you can deploy anywhere            |
| **Agent**         | AI worker that reasons and executes autonomously       |
| **Data Model**    | Structured data table that powers plays                |
| **Object Model**  | Native, writable model owned by your Cargo workspace   |
| **Unified Model** | Read-only model that merges records across all sources |
| **Node**          | Single step in a tool or play                          |
| **Action**        | Operation a node performs (enrich, write, branch)      |
| **Resource**      | Data source (data model, file, or warehouse)           |
| **Run**           | One execution of a play for one record                 |
| **Trigger**       | Condition that starts a play                           |
| **Expression**    | Reference to data: `{{node.field}}`                    |


# Querying orchestration data
Source: https://docs.getcargo.ai/reference/orchestration-query

Read-only ClickHouse SQL over your runs, batches, records and spans: the tables behind alert query scopes, the CLI and the API.

Every run Cargo executes is written to a ClickHouse database you can query directly: four tables (`spans`, `runs`, `records` and `batches`) holding the full execution history of your plays, tools and agents.

Queries are **read-only** and **automatically scoped to your workspace**: you never write a `workspace_uuid` filter, and you can't reach another workspace's data.

## Where you can run a query

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    cargo-ai orchestration query execute \
      "select count(*) from runs where created_at > now() - interval 1 day"
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST "https://api.getcargo.io/v1/orchestration/query" \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"query": "select count(*) from runs"}'
    ```
  </Tab>

  <Tab title="Alert">
    ```ts alerts/error-spike.ts theme={null}
    export const errorSpike = defineAlert("error-spike", {
      schedule: { type: "cron", cron: "@every 15m" },
      scope: {
        kind: "orchestrationQuery",
        query: `select count(*) from spans
                where execution_status = 'error'
                  and execution_started_at > now() - interval 1 hour`,
      },
      threshold: { operator: "gte", value: 50 },
      actions: [{ ref: sentinel, config: { prompt: "{{event.value}} errors" } }],
    });
    ```
  </Tab>
</Tabs>

In the UI, the same engine backs the **Orchestration SQL** scope of the alert editor; see [Using the UI](/alerts/using-ui) and the [query scope reference](/alerts/overview#query-scope).

## This is ClickHouse SQL

The dialect is ClickHouse, not PostgreSQL, so the idioms differ from most warehouses:

| Instead of                  | Write                                 |
| --------------------------- | ------------------------------------- |
| `count(*) filter (where …)` | `countIf(execution_status = 'error')` |
| `now() - interval '1 hour'` | `now() - interval 1 hour`             |
| `extract(epoch from b - a)` | `dateDiff('second', a, b)`            |
| `date_trunc('hour', ts)`    | `toStartOfHour(ts)`                   |

<Warning>
  Before a query reaches ClickHouse it is parsed with a PostgreSQL grammar, so a
  few ClickHouse-only constructs are rejected even though ClickHouse itself
  would accept them. The one you are most likely to hit is **parametric
  aggregates**: `quantile(0.95)(x)` fails to parse. Use `avg(x)`, `min(x)`,
  `max(x)` or `countIf(...)` instead.
</Warning>

## Rules and limits

Only a single `SELECT` runs. `INSERT`, `UPDATE`, `DELETE`, DDL and multiple statements separated by `;` are all rejected before execution, as is any table other than the four below. Reference them unqualified (`spans`, not `orchestration.spans`) and name your own CTEs freely.

| Limit                  | Value             |
| ---------------------- | ----------------- |
| Rows returned          | 10,000            |
| Execution time         | 30s               |
| Rows scanned           | 10 million        |
| Memory                 | 1 GB              |
| Columns read per query | 50                |
| Subquery depth         | 5                 |
| Query length           | 10,000 characters |

<Note>
  All four tables are `ReplacingMergeTree`, and queries run with `FINAL`: you
  always see the latest version of each row, with no deduplication of your own
  needed.
</Note>

## `spans`

One row **per node execution**, the table to reach for when you're measuring how individual actions behave. Runs that were idle or skipped never produce spans.

| Column                             | Type        | Meaning                                            |
| ---------------------------------- | ----------- | -------------------------------------------------- |
| `workspace_uuid`                   | UUID        | Your workspace. Filtered automatically             |
| `workflow_uuid`                    | UUID        | The workflow behind the play or tool               |
| `user_uuid`                        | UUID?       | Who started the run                                |
| `batch_uuid`                       | UUID        | Batch the run belongs to                           |
| `trace_uuid`                       | UUID        | Groups everything triggered together               |
| `record_id`                        | String      | The record the run processed                       |
| `record_title`                     | String      | That record's title                                |
| `run_uuid`                         | UUID        | The run this span belongs to                       |
| `run_context_s3_filename`          | String      | Internal: run context artifact                     |
| `run_computed_configs_s3_filename` | String      | Internal: resolved node configs                    |
| `parent_run_uuid`                  | UUID?       | Run that spawned this one                          |
| `parent_node_uuid`                 | UUID?       | Node that spawned it                               |
| `parent_batch_uuid`                | UUID?       | Batch that spawned it                              |
| `parent_agent_uuid`                | UUID?       | Agent that spawned it, the agent-trigger case      |
| `parent_chat_uuid`                 | UUID?       | Chat that spawned it                               |
| `parent_message_uuid`              | UUID?       | Message that spawned it                            |
| `is_group_parent`                  | Bool?       | Whether the run is the parent of a group execution |
| `node_uuid`                        | UUID        | The node that executed                             |
| `node_kind`                        | Enum        | `native`, `connector`, `tool` or `agent`           |
| `node_slug`                        | String      | The node's slug in the workflow                    |
| `node_action_slug`                 | String      | The action it ran, e.g. `postMessage`              |
| `node_connector_uuid`              | UUID?       | Connector used, for connector nodes                |
| `node_integration_slug`            | String?     | Integration used, e.g. `slack`                     |
| `node_tool_uuid`                   | UUID?       | Tool called, for tool nodes                        |
| `node_agent_uuid`                  | UUID?       | Agent called, for agent nodes                      |
| `node_release_uuid`                | UUID?       | Release the node ran from                          |
| `node_batch_uuid`                  | UUID?       | Batch the node spawned                             |
| `node_run_uuid`                    | UUID?       | Run the node spawned                               |
| `node_message_uuid`                | UUID?       | Message the node produced                          |
| `node_child_index`                 | Int32?      | Position within a group's children                 |
| `node_wait_until_finished`         | Bool        | Whether the node blocked on what it spawned        |
| `node_next_uuid`                   | UUID?       | Next node in the workflow                          |
| `execution_index`                  | UInt32      | Position of this execution within the run, from 0  |
| `execution_status`                 | Enum        | `error`, `pending` or `success`                    |
| `execution_error_message`          | String?     | Why it failed                                      |
| `execution_title`                  | String?     | Human-readable title, as shown in the Spans view   |
| `execution_icon_url`               | String?     | Icon shown alongside it                            |
| `execution_credits_used_count`     | Float32     | Credits this execution consumed                    |
| `execution_started_at`             | DateTime64  | When it started                                    |
| `execution_updated_at`             | DateTime64  | When it last changed                               |
| `execution_finished_at`            | DateTime64? | When it finished, null while pending               |

<Tip>
  `spans` is partitioned by month on `execution_started_at`, so a query that
  bounds that column reads far less data than one that doesn't. It also has 41
  columns against a 50-column budget, so prefer naming the columns you need over
  `select *`.
</Tip>

## `runs`

One row **per run**, the whole execution of one record through one workflow. Unlike `spans`, this includes runs that ended up `idle` or `skipped`.

| Column                         | Type        | Meaning                                                                                |
| ------------------------------ | ----------- | -------------------------------------------------------------------------------------- |
| `uuid`                         | UUID        | The run                                                                                |
| `workspace_uuid`               | UUID        | Your workspace. Filtered automatically                                                 |
| `workflow_uuid`                | UUID        | The workflow it ran                                                                    |
| `user_uuid`                    | UUID?       | Who started it                                                                         |
| `batch_uuid`                   | UUID        | Batch it belongs to                                                                    |
| `trace_uuid`                   | UUID        | Groups everything triggered together                                                   |
| `release_uuid`                 | UUID?       | Release it ran from                                                                    |
| `record_id`                    | String      | The record it processed                                                                |
| `record_title`                 | String      | That record's title                                                                    |
| `status`                       | Enum        | `idle`, `pending`, `running`, `success`, `error`, `skipped`, `cancelling`, `cancelled` |
| `error_message`                | String?     | Why it failed                                                                          |
| `executions`                   | Nested      | Per-node executions (see below)                                                        |
| `created_at`                   | DateTime64  | When it was created                                                                    |
| `updated_at`                   | DateTime64  | When it last changed                                                                   |
| `finished_at`                  | DateTime64? | When it finished                                                                       |
| `deleted_at`                   | DateTime64? | Set when soft-deleted                                                                  |
| `group`                        | Tuple       | `batch_uuid`, `run_uuid`, `node_uuid` of the group it belongs to                       |
| `parent_uuid`                  | UUID?       | Run that spawned it                                                                    |
| `parent_node_uuid`             | UUID?       | Node that spawned it                                                                   |
| `parent_batch_uuid`            | UUID?       | Batch that spawned it                                                                  |
| `parent_agent_uuid`            | UUID?       | Agent that spawned it                                                                  |
| `parent_chat_uuid`             | UUID?       | Chat that spawned it                                                                   |
| `parent_message_uuid`          | UUID?       | Message that spawned it                                                                |
| `is_group_parent`              | Bool?       | Whether it is the parent of a group execution                                          |
| `temporal_workflow_id`         | UUID        | Internal: Temporal workflow instance                                                   |
| `stringified_nodes`            | String?     | Internal: JSON snapshot of the workflow's nodes                                        |
| `context_s3_filename`          | String      | Internal: run context artifact                                                         |
| `computed_configs_s3_filename` | String      | Internal: resolved node configs                                                        |

### The `executions` nested column

`runs` and `records` both carry the run's node executions as a nested column, which reads as parallel arrays: `executions.status`, `executions.credits_used_count`, and so on. Its fields mirror the `spans` columns of the same name, minus the `node_`/`execution_` prefixes: `node_uuid`, `node_slug`, `node_kind`, `node_action_slug`, `node_connector_uuid`, `node_integration_slug`, `node_tool_uuid`, `node_agent_uuid`, `node_release_uuid`, `node_batch_uuid`, `node_run_uuid`, `node_message_uuid`, `node_child_index`, `node_wait_until_finished`, `next_node_uuid`, `status`, `error_message`, `title`, `icon_url`, `credits_used_count`, `started_at`, `updated_at`, `finished_at`.

Array functions work on them directly, so you can ask how many steps a run took, what it cost, whether any step failed:

```sql theme={null}
select
  uuid,
  length(executions.node_uuid) as steps,
  arraySum(executions.credits_used_count) as credits
from runs
where created_at > now() - interval 1 day
  and countEqual(executions.status, 'error') > 0
```

<Warning>
  `array join` is **rejected**: the validator reads the joined nested column as
  a table name, and only `spans`, `runs`, `batches` and `records` are allowed.
  To work one row per execution, query `spans`: it is exactly that flattening,
  precomputed, unless you need runs that were idle or skipped.
</Warning>

## `records`

The same shape as `runs`, keyed by the record rather than the run, and excluding idle and skipped runs. Use it to answer "what happened to this record", where `runs` answers "what did this execution do".

It differs from `runs` in four places: `id` and `title` replace `record_id` and `record_title`, `run_uuid` replaces `uuid`, `parent_run_uuid` replaces `parent_uuid`, and `status` can't be `idle` or `skipped`. There is no `deleted_at`. Everything else, including `executions`, is identical.

## `batches`

One row **per batch**, a play or tool triggered over a set of records.

| Column                 | Type        | Meaning                                                                                               |
| ---------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
| `uuid`                 | UUID        | The batch                                                                                             |
| `workspace_uuid`       | UUID        | Your workspace. Filtered automatically                                                                |
| `workflow_uuid`        | UUID        | The workflow it ran                                                                                   |
| `user_uuid`            | UUID?       | Who triggered it                                                                                      |
| `trace_uuid`           | UUID?       | Groups everything triggered together                                                                  |
| `release_uuid`         | UUID?       | Release it ran from                                                                                   |
| `status`               | Enum        | `pending`, `syncing`, `querying`, `running`, `success`, `error`, `skipped`, `cancelling`, `cancelled` |
| `error_message`        | String?     | Why it failed                                                                                         |
| `runs_count`           | Int32       | Runs the batch created                                                                                |
| `executed_runs_count`  | Int32       | Runs that actually executed                                                                           |
| `failed_runs_count`    | Int32       | Runs that failed                                                                                      |
| `runs_status`          | Enum?       | `healthy` or `unhealthy`, from the outcome of its runs                                                |
| `credits_used_count`   | Float32     | Credits the whole batch consumed                                                                      |
| `created_at`           | DateTime64  | When it was created                                                                                   |
| `updated_at`           | DateTime64  | When it last changed                                                                                  |
| `finished_at`          | DateTime64? | When it finished                                                                                      |
| `data`                 | Tuple       | What triggered it (see below)                                                                         |
| `temporal_workflow_id` | UUID        | Internal: Temporal workflow instance                                                                  |
| `stringified_nodes`    | String?     | Internal: JSON snapshot of the workflow's nodes                                                       |

`data.kind` names the trigger (`segment`, `change`, `filter`, `recordIds`, `records`, `file`, `runs`, `group`, `schedule`, `form` or `watchedRecords`), and the rest of the tuple carries the trigger's payload: `model_uuid`, `segment_uuid`, `change_uuid`, `change_kinds`, `ids`, `limit`, `webhook_url`, the `stringified_*` filter and sort, the `parent_*` and `group_*` links, and the record counts `total_records_count`, `added_records_count`, `updated_records_count`, `removed_records_count` and `unchanged_records_count`. Read a field with dot access: `data.kind`, `data.segment_uuid`.

## Example queries

Error rate over the last hour, as a percentage:

```sql theme={null}
select 100.0 * countIf(execution_status = 'error') / nullif(count(*), 0)
from spans
where execution_started_at > now() - interval 1 hour
```

`nullif` on the divisor keeps an hour without spans as a `NULL` rather than the
`0 / 0` a bare `count(*)` would give. As an alert scope that reads as an empty
window, so a quiet hour never reports a rate.

The slowest integrations yesterday:

```sql theme={null}
select
  node_integration_slug,
  count(*) as executions,
  avg(dateDiff('millisecond', execution_started_at, execution_finished_at) / 1000) as avg_seconds
from spans
where execution_finished_at is not null
  and execution_started_at > now() - interval 1 day
  and node_integration_slug is not null
group by node_integration_slug
order by avg_seconds desc
```

Credits burned per tool this week:

```sql theme={null}
select node_tool_uuid, sum(execution_credits_used_count) as credits
from spans
where execution_started_at > now() - interval 7 day
  and node_tool_uuid is not null
group by node_tool_uuid
order by credits desc
```

Batches that finished unhealthy today:

```sql theme={null}
select uuid, workflow_uuid, runs_count, failed_runs_count
from batches
where runs_status = 'unhealthy'
  and created_at > now() - interval 1 day
order by failed_runs_count desc
```

The most common error messages, grouped:

```sql theme={null}
select execution_error_message, count(*) as occurrences
from spans
where execution_status = 'error'
  and execution_started_at > now() - interval 1 day
group by execution_error_message
order by occurrences desc
```

<Warning>
  A query used as an alert scope is **not** windowed for you: it runs exactly
  as written on every tick. Keep the `interval` bound in the query itself, and
  make it return a single numeric value: the alert reads the first column of the
  first row.
</Warning>

## Next steps

<CardGroup>
  <Card title="Alert on a query" icon="bell" href="/alerts/overview#query-scope">
    Turn any of these queries into a scheduled threshold check that fires
    actions when it breaches.
  </Card>

  <Card title="Monitor from the CLI" icon="chart-line" href="/deploy/monitoring">
    List runs, batches, spans and traces without writing SQL.
  </Card>
</CardGroup>


# Secrets & environments
Source: https://docs.getcargo.ai/reference/secrets-and-environments

How env(), secret() and workspaceEnv() differ, the CARGO_* environment variables the CLI reads, and how to promote the same project code to a second workspace.

Cargo resolves credentials and configuration from your environment — both inside
`define*` resources (`env()` / `secret()` / `workspaceEnv()`) and for the CLI
itself (`CARGO_*` variables). This page covers both, and how to deploy the same
code to more than one workspace.

## `env()`, `secret()` and `workspaceEnv()`

Three helpers, each with one behaviour. The first two read your local
environment; the third reads nothing locally and points at the workspace's own
[environment variables](#workspace-environment-variables):

| Helper                | Reads              | Resolved          | In the content hash & deploy state? | Use for                                                    |
| --------------------- | ------------------ | ----------------- | ----------------------------------- | ---------------------------------------------------------- |
| `env("NAME")`         | `process.env.NAME` | at **load** time  | **Yes** — the value enters the spec | Non-secret config you *want* tracked (region, base URL, …) |
| `secret("NAME")`      | `process.env.NAME` | at **apply** time | **No** — only a reference is stored | A credential this deploy supplies                          |
| `workspaceEnv("KEY")` | nothing locally    | at **apply** time | **No** — only a pointer is stored   | A credential the workspace holds and rotates               |

```ts connectors/hubspot.ts theme={null}
import { defineConnector, env, secret, workspaceEnv } from "@cargo-ai/cdk";

export const hubspot = defineConnector("hubspot", {
  integration: "hubspot",
  config: {
    method: "privateApp",
    accessToken: secret("HUBSPOT_API_KEY"), // this deploy's value, never hashed
    region: env("HUBSPOT_REGION"), // tracked in the content hash
  },
});

export const salesforce = defineConnector("salesforce", {
  integration: "salesforce",
  config: {
    // Read from the workspace on every use — rotate it there, no redeploy
    accessToken: workspaceEnv("SALESFORCE_TOKEN"),
  },
});
```

<Warning>
  Always use `secret()` or `workspaceEnv()` — never `env()` — for credentials.
  Both are excluded from the content hash and from the deploy state; `env()`
  bakes the value into the hash, so rotating it reads as drift and the value is
  written to state.
</Warning>

### How each behaves

* **`env("NAME")`** reads `process.env.NAME` when the file is imported and inlines
  the value into the spec. If the variable is unset it returns a visible
  `${NAME}` placeholder so the gap surfaces in `cargo-ai project plan`.
* **`secret("NAME")`** returns a deferred reference (`EncryptionRef`). At apply
  time the project reads `process.env.NAME`, wraps it in Cargo's encryption
  envelope, and sends it to the API. The deploy fails if the variable is not set
  locally — it does **not** fall back to the workspace catalog, so a credential's
  behaviour never depends on what the deploying machine happened to have
  exported. Because the reference — not the value — enters the spec, **rotating
  a secret doesn't register as drift**, and a plain `deploy` won't push the new
  value (nothing in the hash changed). Re-apply the resource to roll a rotated
  secret: make any other change, or run `cargo-ai project deploy --refresh`.
* **`workspaceEnv("KEY")`** returns a deferred pointer (`WorkspaceEnvRef`). At
  apply time it becomes a reference to the workspace variable named `KEY`; the
  value stays server-side and never reaches the deploying machine. It is read
  again on every use, so rotating it needs no re-apply at all — see
  [rotating a value](#rotating-a-value). `cargo-ai project plan` fails if the
  workspace holds no such variable.

### Where each is accepted

The distinction is load-bearing, and the generated types enforce it:

| Position                                                         | Accepts                                                |
| ---------------------------------------------------------------- | ------------------------------------------------------ |
| Connector and system-of-record `config`                          | `secret()` or `workspaceEnv()` (typed `CredentialRef`) |
| `defineWorker`, `defineApp`, `defineAgent`, `defineScript` `env` | `env()` or `secret()` (typed `EncryptionRef`)          |

`workspaceEnv()` is deliberately a type error on a resource's own `env`, because
those runtimes already receive **every** workspace variable by inheritance — a
pointer there could only restate a variable the resource can read anyway. Config
is different: a connector's credential is a single field, so pointing it at the
catalog is the only way to make it rotate without a redeploy.

See [State & drift](/deploy/state-and-drift) for how the content hash drives
what a deploy considers changed.

## Workspace environment variables

A workspace holds its own set of environment variables, managed under
**Settings → Environment** (or with `cargo-ai workspaceManagement envVar`).
Store a value once there instead of setting it on every worker, app and agent
that needs it. Secrets are encrypted at rest and their values are never
returned by the API.

Every worker, app and agent in the workspace picks them up automatically — you
do not declare them on the resource:

| Runtime | What it receives                                                   | How to read it              |
| ------- | ------------------------------------------------------------------ | --------------------------- |
| Worker  | Every workspace variable, secrets included                         | `c.env.NAME`                |
| App     | Only **non-secret** variables whose key starts with `VITE_`        | `import.meta.env.VITE_NAME` |
| Agent   | Every workspace variable, in the sandbox its shell commands run in | `process.env.NAME`          |

An app bundle is served to the browser, which is why a secret is never put in
one. Give an app its public configuration under a `VITE_` key and keep the
credential it must not expose on a worker instead.

A variable set on the resource itself **wins** over the workspace variable with
the same key, so a single worker can override one value without a copy of the
rest. That is also what `secret("NAME")` does at deploy time: the value your
shell exports is sent as that resource's own value for this apply, and the
catalog is left untouched.

### Rotating a value

A resource never holds a copy of a workspace variable — it inherits it, or holds
a `workspaceEnv()` pointer, resolved each time the value is needed. Rotating the
value under **Settings → Environment** therefore reaches everything that reads
it, with no redeploy. When it takes effect depends only on when the resource next
reads it:

| Resource                       | A new value takes effect      |
| ------------------------------ | ----------------------------- |
| Connector, native script model | On the next run — immediately |
| Agent                          | On the next message           |
| Worker                         | On its next deployment        |
| App                            | On its next build             |

Workers and apps bake their environment into a build artifact, so those two need
a redeploy. Nothing else does.

<Warning>
  Deleting a variable that a connector still points at breaks it at the next
  run, not at the next deploy. The failure names the missing variable, but check
  what references a value before removing it.
</Warning>

<Note>
  A `workspaceEnv()` pointer is checked at plan time, so a `cargo-ai project deploy`
  naming a variable the workspace does not hold fails before it creates
  anything. That check needs the API; an offline plan skips it.
</Note>

The one exception is an integration that mints its own credentials during
authentication — an OAuth flow that exchanges what you submit for its own
tokens, as HubSpot and Slack do. What ends up stored is the provider's token
rather than your variable, so there is nothing left to keep live and rotating
the variable has no effect. Reconnect the connector instead.

## CLI environment variables

The `cargo-ai` CLI (and therefore `cargo-ai project`) reads three environment
variables. **They take precedence over the saved credentials file**
(`~/.config/cargo-ai/credentials.json`):

| Variable               | Purpose                                      | Default                                 |
| ---------------------- | -------------------------------------------- | --------------------------------------- |
| `CARGO_API_TOKEN`      | API token used to authenticate every request | — (falls back to the saved credentials) |
| `CARGO_WORKSPACE_UUID` | The workspace to operate on                  | — (falls back to the token's workspace) |
| `CARGO_BASE_URL`       | Cargo API base URL                           | `https://api.getcargo.io`               |

In CI or an AI coding agent, set these instead of running `cargo-ai login`:

```bash theme={null}
export CARGO_API_TOKEN=<your-api-token>
export CARGO_WORKSPACE_UUID=<workspace-uuid>   # optional; pins the target workspace
cargo-ai whoami                                # confirms the active token, workspace, and source
```

`whoami` reports the `source` as `environment` when a `CARGO_API_TOKEN` is set,
or `credentials-file` when it's reading the saved login.

## Promoting code to a second workspace

The same project code can deploy to multiple workspaces (e.g. staging → production).
Two things change per workspace; the code does not:

1. **Which workspace you target** — set `CARGO_WORKSPACE_UUID` (or log in to that
   workspace), so `cargo-ai project deploy` resolves the right target.
2. **The secret values** — either export each environment's `secret()` values
   before deploying, or write the code with `workspaceEnv("KEY")` and store the
   value once in each workspace's
   [environment variables](#workspace-environment-variables). The second is
   usually what you want for promotion: each workspace holds its own value under
   the same key, so pointing the same code at production is nothing beyond
   selecting the workspace.

```bash theme={null}
# Deploy the same repo to the production workspace
export CARGO_WORKSPACE_UUID=<prod-workspace-uuid>
export HUBSPOT_API_KEY=<prod-hubspot-key>
cargo-ai project deploy --dir ./prod   # keep prod's deploy state separate
```

<Warning>
  Each workspace needs its **own deploy state** — a state records the workspace
  uuid, and a deploy refuses to run if it belongs to a different workspace than
  the one selected (it would orphan resources). Keep a separate checkout or
  `--dir` per workspace, and run `cargo-ai project state create` in the second one
  so the two have different pointers.
</Warning>

Secrets are never copied between environments through Cargo: deploy state
records only uuids, hashes, and outputs — [never secret values](/deploy/state-and-drift).


# Security
Source: https://docs.getcargo.ai/reference/security

How Cargo protects your data and keeps your workflows secure

Cargo is built with security at its core. We understand that you're trusting us with sensitive business data, and we take that responsibility seriously.

## Infrastructure security

| Feature               | Description                                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Cloud hosting**     | Cargo runs on enterprise-grade cloud infrastructure with 99.9% uptime SLA, automatic failover, and geo-redundant backups. |
| **Network isolation** | All services are designed to run in isolated virtual private clouds, with strict network policies and firewall rules.     |

## Data protection

### Encryption

All data is encrypted both in transit and at rest:

| Layer      | Protection                                               |
| ---------- | -------------------------------------------------------- |
| In transit | TLS 1.3 encryption for all API and web traffic           |
| At rest    | AES-256 encryption for all stored data                   |
| Database   | Encrypted storage with customer-isolated data partitions |
| Backups    | Encrypted backups with point-in-time recovery            |

### Data handling

<Steps>
  <Step title="Minimal data retention">
    Cargo only stores data necessary to run your workflows. Intermediate
    processing data is automatically purged after execution.
  </Step>

  <Step title="Customer isolation">
    Each workspace's data is logically isolated. Strict access controls ensure
    no cross-tenant data access.
  </Step>

  <Step title="Secure deletion">
    When you delete data or close your account, we permanently remove all
    associated data from our systems.
  </Step>
</Steps>

## Access control

### Authentication

* **Single Sign-On (SSO)**: Connect your identity provider for centralized authentication
* **Multi-factor authentication (MFA)**: Add an extra layer of security to user accounts
* **API keys**: Scoped, rotatable keys for programmatic access with granular permissions

### Permissions

Cargo provides role-based access control (RBAC) to manage what users can do within your workspace:

| Role   | Capabilities                                                   |
| ------ | -------------------------------------------------------------- |
| Admin  | Full access to all settings, integrations, and user management |
| Editor | Create and modify tools, agents, plays, and data models        |
| Viewer | Read-only access to view workflows and results                 |

Workspaces can also define **custom roles** under Settings → Roles. A custom role is a named permission bundle with per-domain access (disabled, read, or read & write). Seeded system roles cannot be edited or deleted.

## Compliance

| Certification     | Description                                                                                                                                                                        |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SOC 2 Type II** | Cargo maintains SOC 2 Type II certification, demonstrating our commitment to security, availability, and confidentiality.                                                          |
| **GDPR-aligned**  | We align with GDPR requirements and provide Data Processing Agreements (DPA) as well as support data subject access requests. Note: Cargo does not hold formal GDPR certification. |

### Data residency

Cargo supports data residency requirements for customers with specific regional data storage needs. Contact us to discuss your requirements.

## Integration security

### Warehouse connections

When connecting to your data warehouse (Snowflake, BigQuery), Cargo:

* Uses read-only credentials where possible
* Connects via secure, encrypted channels
* Never stores raw credentials — they're encrypted and isolated in secure vaults

### CRM and third-party integrations

All OAuth connections follow best practices:

* Minimal permission scopes requested
* Tokens securely stored and automatically refreshed
* Connections can be revoked at any time from your workspace

## Monitoring and incident response

| Feature               | Description                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------------- |
| **24/7 monitoring**   | Automated systems continuously monitor for security threats and anomalies.                  |
| **Incident response** | Documented incident response procedures with defined SLAs for communication and resolution. |

## Reporting vulnerabilities

If you discover a security vulnerability, please report it responsibly by emailing **[security@getcargo.ai](mailto:security@getcargo.ai)**. We appreciate your help in keeping Cargo secure and will acknowledge your report within 24 hours.

## Questions?

For security-related inquiries or to request our SOC 2 report, contact us at [security@getcargo.ai](mailto:security@getcargo.ai).


# Overview
Source: https://docs.getcargo.ai/reference/system-of-record

How Cargo stores the GTM system of record — on Cargo's warehouse, or on your BigQuery or Snowflake — and how to operate it from the CLI.

Cargo is the GTM system of record: companies, contacts, deals, and custom objects, stored, synced, and unified in one place, built for scale.

Under the hood that data lives in a cloud data warehouse. Cargo ships a **managed BigQuery** by default; you can run the same system of record **on top of your own BigQuery or Snowflake**. That warehouse layer is why the models query with SQL and scale to billions of records.

This page is how you connect and operate that warehouse. The `cargo-ai system-of-record` domain manages credentials, schema migrations, and cutover.

## Connect a warehouse

Cargo ships with a **default managed BigQuery** warehouse, so you can start immediately. To bring your own warehouse, follow the setup guide for your provider — it walks through the permissions, credentials, and the **Workspace settings → System of record** form:

<CardGroup>
  <Card title="BigQuery" icon="google" href="/reference/system-of-record/bigquery">
    Use Cargo's default BigQuery or connect your existing Google Cloud project (service account, storage bucket, scope).
  </Card>

  <Card title="Snowflake" icon="snowflake" href="/reference/system-of-record/snowflake">
    Connect your existing Snowflake instance (roles, RSA key, IP allowlist).
  </Card>
</CardGroup>

Once connected, manage the SOR lifecycle from the CLI.

## Create and inspect

```bash theme={null}
cargo-ai system-of-record sor list
cargo-ai system-of-record sor get <sor-uuid>
cargo-ai system-of-record sor create --kind <kind> --config '{ ... }'
cargo-ai system-of-record sor update --uuid <sor-uuid> --config '{ ... }'
```

## Migrate and cut over

Schema changes are staged as a migration, then promoted with a cutover so live reads switch atomically:

```bash theme={null}
cargo-ai system-of-record sor migrate <sor-uuid>   # stage a schema change
cargo-ai system-of-record sor cutover <sor-uuid>   # promote it live
```

## Query the synced data

```bash theme={null}
cargo-ai system-of-record client get-documentation <slug>      # queryable schema
```

## Monitor sync health

```bash theme={null}
cargo-ai system-of-record log list
cargo-ai system-of-record log get-metrics --from 2025-01-01 --to 2025-01-31
```

## Using the UI

The workspace also surfaces SOR status, migrations, and sync logs visually — use the CLI for scripted setup and migrations, and the UI to review sync health at a glance.


# Set up Cargo on BigQuery
Source: https://docs.getcargo.ai/reference/system-of-record/bigquery

Configure BigQuery as your system of record in Cargo

This guide walks you through setting up BigQuery as your system of record in Cargo. By the end, Cargo will have the necessary permissions to read and write data efficiently.

<Note>
  Cargo ships with a **default managed BigQuery** warehouse, so connecting your
  own warehouse is optional. Follow this guide to use your existing Google Cloud
  BigQuery project instead. See [System of record](/reference/system-of-record)
  for what a SOR is and how to operate it from the CLI once connected.
</Note>

## Permissions

**What Cargo can do**

* Read data from datasets and tables, even if they are spread across multiple projects
* Write data into new datasets and tables

**What Cargo will never do**

* Overwrite existing datasets and tables (Cargo always creates its own datasets and tables when needed)

## Before you begin

You need an existing Google Cloud Project with a payment method and billing enabled. [Follow the official Google guide](https://developers.google.com/workspace/guides/create-project) to create one.

This guide covers enabling and creating the following elements in your GCP project:

* BigQuery API & Cloud Resource Manager API
* Cloud Storage bucket (dedicated to Cargo)
* Service Account with appropriate permissions

<Note>
  If you have an existing BigQuery project and technical knowledge, you may skip
  any steps you've already completed.
</Note>

### Enable the necessary APIs

Cargo uses two Google APIs that must be enabled:

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Select **APIs & Services**
3. Select **Enabled APIs & Services**
4. Search for and enable the following APIs:
   * `BigQuery API`
   * `Cloud Resource Manager API`

### Create a storage bucket

To enable Cargo to load and unload data from BigQuery as your system of record, you need a dedicated storage bucket.

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Search for **Cloud Storage** in the search bar
3. Click **Create bucket** and follow the setup wizard
4. Note down the bucket name and location for later

## Step 1: Create a service account

Create a service account with the necessary permissions for Cargo to interact with BigQuery.

<Tabs>
  <Tab title="Console">
    1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
    2. Navigate to **IAM & Admin** → **Service Accounts**
    3. Click **Create service account**
    4. Give the service account a name (e.g., `cargo-bigquery`)
    5. Grant the following roles:
       * `BigQuery Data Editor` – Read and write data in BigQuery tables
       * `BigQuery Job User` – Run queries and jobs
       * `Storage Object User` – Read/write to the Cloud Storage bucket
    6. Click **Done**
    7. Click on the newly created service account
    8. Go to the **Keys** tab
    9. Click **Add Key** → **Create new key** → **JSON**
    10. Save the downloaded JSON file securely—you'll need its contents for the connection
  </Tab>

  <Tab title="CLI">
    **Create the service account:**

    ```bash theme={null}
    gcloud iam service-accounts create cargo-bigquery \
        --display-name="Cargo BigQuery Service Account"
    ```

    **Grant BigQuery and Storage permissions:**

    ```bash theme={null}
    gcloud projects add-iam-policy-binding your-project-id \
        --member="serviceAccount:cargo-bigquery@your-project-id.iam.gserviceaccount.com" \
        --role="roles/bigquery.dataEditor"

    gcloud projects add-iam-policy-binding your-project-id \
        --member="serviceAccount:cargo-bigquery@your-project-id.iam.gserviceaccount.com" \
        --role="roles/bigquery.jobUser"

    gcloud projects add-iam-policy-binding your-project-id \
        --member="serviceAccount:cargo-bigquery@your-project-id.iam.gserviceaccount.com" \
        --role="roles/storage.objectUser"
    ```

    **Create and download a key file:**

    ```bash theme={null}
    gcloud iam service-accounts keys create cargo-bigquery-key.json \
        --iam-account=cargo-bigquery@your-project-id.iam.gserviceaccount.com
    ```
  </Tab>
</Tabs>

## Step 2: Grant additional permissions (optional)

If you need Cargo to access data outside the default dataset, grant read access to other datasets:

```bash theme={null}
bq add-iam-policy-binding \
    --member="serviceAccount:cargo-bigquery@your-project-id.iam.gserviceaccount.com" \
    --role="roles/bigquery.dataViewer" \
    your-project-id:other_dataset
```

## Step 3: Verify permissions

Ensure the Cargo service account has the following permissions:

| Permission                   | Purpose           |
| ---------------------------- | ----------------- |
| `bigquery.tables.create`     | Create new tables |
| `bigquery.tables.getData`    | Read table data   |
| `bigquery.tables.updateData` | Update table data |
| `bigquery.jobs.create`       | Run BigQuery jobs |

**Check service account permissions:**

```bash theme={null}
gcloud projects get-iam-policy your-project-id \
    --flatten="bindings[].members" \
    --format='table(bindings.role)' \
    --filter="bindings.members:cargo-bigquery@your-project-id.iam.gserviceaccount.com"
```

## Step 4: Connect to Cargo

Now that everything is set up, connect BigQuery as your system of record in Cargo:

1. Navigate to **Workspace settings** → **System of record**
2. Fill in the settings form:
   * **Service Account**: Paste the contents of your JSON key file
   * **Location**: Select the location you chose when creating the storage bucket
   * **Bucket**: Enter the name of your storage bucket
   * **Scope**: Select `Dataset`
   * **Dataset**: Enter the name of your dedicated dataset for Cargo (e.g., `cargo_dataset`)
3. Click **Setup**

<Check>Your BigQuery integration is now complete!</Check>

## Next steps

<CardGroup>
  <Card title="System of record" icon="database" href="/reference/system-of-record">
    Query, migrate, and monitor your SOR from the CLI.
  </Card>

  <Card title="Query your data" icon="code" href="/models/querying">
    Build data models and run SQL against your warehouse.
  </Card>

  <Card title="BigQuery actions" icon="google" href="/integration/big-query">
    Use insert, update, upsert, and delete actions in workflows.
  </Card>

  <Card title="Models" icon="table" href="/models/overview">
    Create data models on top of your BigQuery tables.
  </Card>
</CardGroup>


# Set up Cargo on Snowflake
Source: https://docs.getcargo.ai/reference/system-of-record/snowflake

Configure Snowflake as your system of record in Cargo

This guide walks you through setting up Snowflake as your system of record in Cargo. This setup ensures Cargo has the necessary permissions in Snowflake to read and write data efficiently.

<Note>
  Cargo ships with a **default managed BigQuery** warehouse, so you can start
  without connecting anything. Follow this guide only if you want to bring your
  own Snowflake instance. See [System of record](/reference/system-of-record)
  for what a SOR is and how to operate it from the CLI once connected.
</Note>

### Permissions

**What Cargo can do**

* Read data from schemas and tables, even if they are spread across multiple databases
* Write data into new schemas and tables

**What Cargo will never do**

* Overwrite existing schemas and tables (Cargo always creates its own schemas and tables when needed)

### Before you begin

To start, you need an existing Snowflake account with appropriate admin access to create databases, warehouses, roles, and users.

### Step 1: Create a dedicated database

Create a dedicated database for Cargo where all data managed by Cargo will be stored.

**Create a database called "cargo\_db"**

```sql theme={null}
CREATE DATABASE cargo_db;
```

### Step 2: Create a user for Cargo

Grant the necessary permissions for Cargo to run commands as an authenticated user on the database you just created.

**Create a role for Cargo**

```sql theme={null}
CREATE ROLE cargo_role;
```

**Grant the cargo database you created above to cargo role**

```sql theme={null}
GRANT ALL ON DATABASE cargo_db TO ROLE cargo_role;
```

**Create a warehouse for Cargo**

```sql theme={null}
CREATE WAREHOUSE cargo_wh
  WITH WAREHOUSE_SIZE = 'XSMALL'
  WAREHOUSE_TYPE = 'STANDARD'
  AUTO_SUSPEND = 60
  AUTO_RESUME = TRUE;
```

**Grant warehouse to cargo role**

```sql theme={null}
GRANT USAGE ON WAREHOUSE cargo_wh TO ROLE cargo_role;
```

**Create a user for Cargo**

<Warning>
  Replace `<YOUR_SECURE_PASSWORD>` with a strong, unique password. Store it securely — you'll need it in Step 6.
</Warning>

```sql theme={null}
CREATE USER cargo_user
  PASSWORD = '<YOUR_SECURE_PASSWORD>'
  DEFAULT_ROLE = cargo_role
  DEFAULT_WAREHOUSE = cargo_wh
  MUST_CHANGE_PASSWORD = FALSE;
```

**Grant role to user**

```sql theme={null}
GRANT ROLE cargo_role TO USER cargo_user;
```

**Grant access to schema tables**

If Cargo needs to access data outside the `cargo_db` database, grant the appropriate permissions:

```sql theme={null}
GRANT SELECT ON ALL TABLES IN SCHEMA cargo_db.public TO ROLE cargo_role;
```

<Tip>
  To grant access to other databases, run similar `GRANT` statements for each
  database/schema Cargo needs to read from.
</Tip>

### Step 3: Verify granted privileges

Make sure the Cargo role has access to the following permissions on `cargo_db`: `OWNERSHIP`, `MODIFY`, `MONITOR`, `USAGE`, `CREATE SCHEMA`.

**Show granted privileges on cargo\_db**

```sql theme={null}
SHOW GRANTS ON DATABASE cargo_db;
```

***

### Step 4: Set up RSA key authentication

You must provide an RSA private key for authentication.

**Generate a private key**

```bash theme={null}
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
```

**Generate a public key**

```bash theme={null}
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
```

<Warning>
  Keep your private key (`rsa_key.p8`) secure and never share it. You'll need to
  provide it when configuring Cargo.
</Warning>

**Assign the public key to your Snowflake user**

Copy the contents of `rsa_key.pub` (excluding the header and footer lines) and run:

```sql theme={null}
ALTER USER cargo_user SET RSA_PUBLIC_KEY = 'MIIBIjANBgkqh...your_public_key_here...';
```

***

### Step 5: Configure allowed IP addresses

If you're using Snowflake's network policy to restrict access, add these Cargo IP addresses to your allowlist:

| IP Address      |
| --------------- |
| `3.251.34.134`  |
| `54.220.135.99` |
| `79.125.105.52` |

***

### Step 6: Set up system of record

Now that we have all the required elements, navigate to workspace settings and select **System of record**.

Fill in the settings form with the data we gathered in the previous steps:

| Field           | Value                                   |
| --------------- | --------------------------------------- |
| Account name    | Your Snowflake account identifier       |
| Database        | `cargo_db` (created in Step 1)          |
| Warehouse       | `cargo_wh` (created in Step 2)          |
| Role            | `cargo_role` (created in Step 2)        |
| User            | `cargo_user` (created in Step 2)        |
| Password        | The password you set in Step 2          |
| RSA Private Key | Contents of `rsa_key.p8`                |
| Scope           | Choose **Database** or **Schema** scope |

<Info>
  **Database scope** allows Cargo to create multiple schemas within `cargo_db`.
  **Schema scope** restricts Cargo to a single schema.
</Info>

Click **Setup** to complete the configuration.

***

### Next steps

<CardGroup>
  <Card title="System of record" icon="database" href="/reference/system-of-record">
    Query, migrate, and monitor your SOR from the CLI.
  </Card>

  <Card title="Query your data" icon="code" href="/models/querying">
    Build data models and run SQL against your warehouse.
  </Card>

  <Card title="Snowflake actions" icon="snowflake" href="/integration/snowflake">
    Insert, update, upsert, and delete records in workflows.
  </Card>

  <Card title="Models" icon="table" href="/models/overview">
    Create data models on top of your Snowflake tables.
  </Card>
</CardGroup>


# Examples
Source: https://docs.getcargo.ai/skills/examples

Worked examples for the most common Cargo tasks — run tools, trigger plays, query the warehouse, build workflows, deploy agents, and more.

Each example shows the plain-English prompt, what the agent does step by step, and the exact CLI commands it runs.

***

## Run a workflow on a single record

**Prompt:**

```
Run the lead enrichment tool on Acme Inc. (domain: acme.com)
```

**What the agent does:**

1. `cargo-ai orchestration tool list` — finds `workflowUuid` for the enrichment tool
2. `cargo-ai orchestration run create` with the record data, waits for completion
3. Parses and presents the result

```bash theme={null}
cargo-ai orchestration run create \
  --workflow-uuid <tool.workflowUuid> \
  --data '{"company":"Acme Inc.","domain":"acme.com"}' \
  --wait-until-finished
```

<Note>
  `run create` works with **tool** workflows only. For plays, use `batch create`
  instead.
</Note>

***

## Trigger a batch play across a segment

**Prompt:**

```
Trigger the MQL scoring play on all leads added this week.
```

**What the agent does:**

1. `cargo-ai orchestration play list` — finds `workflowUuid` and `modelUuid`
2. `cargo-ai orchestration batch create` with a filter over the model
3. Polls `batch get` every 5 seconds until terminal status
4. Reports `runsCount`, `executedRunsCount`, `failedRunsCount`

```bash theme={null}
# Discover the play
cargo-ai orchestration play list

# Trigger over the play's model
cargo-ai orchestration batch create \
  --workflow-uuid <play.workflowUuid> \
  --data '{"kind":"filter","modelUuid":"<play.modelUuid>"}' \
  --wait-until-finished

# Check result
cargo-ai orchestration batch get <batch-uuid>
# → {"batch":{"runsCount":450,"executedRunsCount":450,"failedRunsCount":3,...}}
```

<Warning>
  A batch with `status: "success"` can still contain individual run failures.
  Always inspect `failedRunsCount` and re-queue as needed.
</Warning>

***

## Query your data warehouse

**Prompt:**

```
How many companies in our model have more than 500 employees and are headquartered in the US?
```

**What the agent does:**

1. `cargo-ai storage model list` — finds the Companies model's dataset and model slugs
2. `cargo-ai storage model get-ddl <uuid>` — gets the exact column names and types
3. Composes and executes a SQL query

```bash theme={null}
# Step 1: Get the DDL for the exact column names and types
cargo-ai storage model get-ddl <model-uuid>
# → {"ddl":"CREATE TABLE `datasets_default.models_companies` (name STRING, domain STRING, employee_count INT64, country STRING, ...)"}

# Step 2: Reference the model logically as <dataset-slug>.<model-slug>
cargo-ai storage query execute \
  "SELECT COUNT(*) as total FROM default.companies WHERE employee_count > 500 AND country = 'US'"
# → {"outcome":"queried","rows":[{"total":142}]}
```

<Warning>
  In `storage query`, reference models as `<dataset-slug>.<model-slug>` (e.g.
  `default.companies`) — not the physical `datasets_…/models_…` name. Run
  `model get-ddl` first to confirm the available columns and types.
</Warning>

***

## Build a workflow from scratch

<Note>
  This example builds a workflow imperatively — assembling a raw node graph and
  validating it with `node validate`. For a **versioned, reviewable** workflow,
  author it declaratively instead with
  [`defineWorkflow`](/workflows/overview) in a project and ship it with
  `cargo-ai project deploy`. Use this imperative path for one-off or
  agent-constructed graphs.
</Note>

**Prompt:**

```
Build a workflow that enriches company domains with Clearbit and writes the results back to the Companies model.
```

**What the agent does:**

1. `cargo-ai connection connector list --integration-slug clearbit` — finds `connectorUuid`
2. `cargo-ai connection integration get clearbit` — gets available `actionSlug` values and their config schemas (via `manifest.actions.<actionSlug>.config.jsonSchema`)
3. `cargo-ai storage model list` — finds the Companies model UUID
4. Assembles and validates a node graph, then executes

```bash theme={null}
# Step 1: Find the Clearbit connector
cargo-ai connection connector list --integration-slug clearbit
# → [{"uuid":"clearbit-connector-uuid","name":"Clearbit - Prod","integrationSlug":"clearbit"}]

# Step 2: Discover available actions and their config schemas
cargo-ai connection integration get clearbit
# → manifest.actions includes actionSlug: "company_enrich"
# → manifest.actions.company_enrich.config.jsonSchema lists required inputs: ["domain"]
# Note: `integration get-documentation` returns plain-text docs only, not machine-readable schemas.

# Step 3: Validate the node graph
cargo-ai orchestration node validate --nodes '[
  {
    "uuid":"00000000-0001-0000-0000-000000000000",
    "slug":"start",
    "kind":"native",
    "actionSlug":"start",
    "config":{},
    "childrenUuids":["00000000-0002-0000-0000-000000000000"],
    "fallbackOnFailure":false,
    "position":{"x":0,"y":0}
  },
  {
    "uuid":"00000000-0002-0000-0000-000000000000",
    "slug":"enrich",
    "kind":"connector",
    "integrationSlug":"clearbit",
    "actionSlug":"company_enrich",
    "connectorUuid":"<clearbit-connector-uuid>",
    "config":{
      "domain":{"kind":"templateExpression","expression":"{{nodes.start.domain}}","instructTo":"none","fromRecipe":false}
    },
    "childrenUuids":["00000000-0003-0000-0000-000000000000"],
    "fallbackOnFailure":false,
    "position":{"x":166,"y":0}
  },
  {
    "uuid":"00000000-0003-0000-0000-000000000000",
    "slug":"end",
    "kind":"native",
    "actionSlug":"end",
    "config":{},
    "childrenUuids":[],
    "fallbackOnFailure":false,
    "position":{"x":332,"y":0}
  }
]'
# → {"outcome":"valid"}

# Step 3b: Look at what you built before you run it — `validate` proves the
# graph is well-formed, not that it does what you meant. Free, runs nothing.
cargo-ai orchestration node diagram --nodes '[...]' --raw
# → flowchart TD
#       n0(["start"])
#       n1["enrich<br/>clearbit.company_enrich"]
#       n2(["end"])
#       n0 --> n1
#       n1 --> n2

# Step 4: Run it
cargo-ai orchestration run create \
  --workflow-uuid <tool.workflowUuid> \
  --data '{"domain":"acme.com"}' \
  --nodes '[...]' \
  --wait-until-finished
```

***

## Create and deploy an AI agent

**Prompt:**

```
Create a lead scoring agent using GPT-4o-mini with a temperature of 0.0, focused on ICP fit.
```

**What the agent does:**

1. `cargo-ai ai agent create` — creates the agent resource
2. `cargo-ai ai release get-draft` — fetches the editable draft
3. `cargo-ai ai release update-draft` — sets model, prompt, temperature
4. `cargo-ai ai release deploy-draft` — publishes the configuration

```bash theme={null}
# Step 1: Create the agent
cargo-ai ai agent create \
  --name "ICP Lead Scorer" \
  --icon-color green \
  --icon-face "📊" \
  --description "Scores leads based on ICP fit from 1 to 10"
# → {"agent":{"uuid":"agent-uuid",...}}

# Step 2: Get the draft
cargo-ai ai release get-draft --agent-uuid <agent-uuid>

# Step 3: Update draft config
cargo-ai ai release update-draft --agent-uuid <agent-uuid> \
  --system-prompt "You are a B2B lead scoring assistant. Given a company's profile, score its fit with our ICP from 1 to 10 and explain your reasoning in 2 sentences." \
  --language-model-slug gpt-4o-mini \
  --temperature 0.0 \
  --max-steps 5

# Step 4: Deploy
cargo-ai ai release deploy-draft --agent-uuid <agent-uuid> \
  --integration-slug openai \
  --language-model-slug gpt-4o-mini \
  --actions '[]' \
  --mcp-clients '[]' \
  --resources '[]' \
  --capabilities '[]' \
  --suggested-actions '[]' \
  --description "Initial deployment — ICP scorer v1"
```

**Model selection guide:**

| Task                                | Recommended model                   | Temperature   |
| ----------------------------------- | ----------------------------------- | ------------- |
| Scoring, classification, extraction | `gpt-4o-mini` or `claude-3-5-haiku` | `0.0` – `0.2` |
| Research, summarization, analysis   | `gpt-4o` or `claude-3-5-sonnet`     | `0.2` – `0.5` |
| Personalized outreach, copywriting  | `gpt-4o` or `claude-3-5-sonnet`     | `0.5` – `0.8` |
| Creative brainstorming              | `gpt-4o` or `claude-opus`           | `0.7` – `1.0` |

***

## Monitor workflow health

**Prompt:**

```
Show me the error rate for the CRM sync play over the last 7 days, broken down by node.
```

**What the agent does:**

1. `cargo-ai orchestration play list` — finds `workflowUuid`
2. `cargo-ai orchestration run get-metrics` with a date range
3. Computes `errorExecutionsCount / totalExecutionsCount` per node

```bash theme={null}
cargo-ai orchestration run get-metrics \
  --workflow-uuid <uuid> \
  --created-after 2025-01-12 \
  --created-before 2025-01-19
```

Response:

```json theme={null}
{
  "runMetrics": [
    {
      "nodeUuid": "enrich-node-uuid",
      "totalExecutionsCount": 1000,
      "successExecutionsCount": 950,
      "errorExecutionsCount": 48,
      "cancelledExecutionsCount": 2,
      "creditsUsedCount": 450
    }
  ]
}
```

Error rate = `48 / 1000 = 4.8%`

**Re-queue failed records:**

```bash theme={null}
# 1. Download failed runs
cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --statuses error \
  --created-after 2025-01-12 > failed_runs.json

# 2. Re-run only the failed records
RECORD_IDS=$(jq '[.[].recordId]' failed_runs.json)
cargo-ai orchestration batch create \
  --workflow-uuid <uuid> \
  --data "{\"kind\":\"recordIds\",\"recordIds\":$RECORD_IDS}"
```

***

## Export segment data

**Prompt:**

```
Export all US companies with fewer than 200 employees, sorted by creation date descending.
```

**What the agent does:**

1. `cargo-ai storage model list` — finds the Companies model UUID
2. `cargo-ai segmentation segment download` with filter and sort

```bash theme={null}
cargo-ai segmentation segment download \
  --model-uuid <companies-model-uuid> \
  --filter '{
    "conjonction": "and",
    "groups": [{
      "conjonction": "and",
      "conditions": [
        {"kind":"string","columnSlug":"country","operator":"is","values":["US"]},
        {"kind":"number","columnSlug":"employee_count","operator":"lowerThan","value":200}
      ]
    }]
  }' \
  --sort '[{"columnSlug":"created_at","kind":"desc"}]'
```

<Note>
  Use `--model-uuid`, not `--segment-uuid`. The filter and sort flags use the
  same JSON schema as the Cargo UI segment builder.
</Note>

***

## Bootstrap a new workspace

**Prompt:**

```
Set up a fresh Cargo workspace: Companies and Contacts models, a HubSpot connector, and a GPT-4o scoring agent.
```

**What the agent does (full sequence across 4 skills):**

```bash theme={null}
# 1. Workspace — create folders for organization
cargo-ai workspaceManagement folder create --name "Enrichment" --emoji-slug "sparkles" --kind tool
cargo-ai workspaceManagement folder create --name "Scoring" --emoji-slug "chart-bar" --kind play

# 2. Storage — create models and columns
cargo-ai storage dataset list   # → datasetUuid
cargo-ai storage model create --slug companies --name "Companies" --dataset-uuid <uuid> --extractor-slug csv --config '{}'
cargo-ai storage model create --slug contacts --name "Contacts" --dataset-uuid <uuid> --extractor-slug csv --config '{}'

cargo-ai storage column create --model-uuid <companies-uuid> \
  --column '{"slug":"domain","type":"string","label":"Domain","kind":"custom"}'
cargo-ai storage column create --model-uuid <companies-uuid> \
  --column '{"slug":"employee_count","type":"number","label":"Employees","kind":"custom"}'
cargo-ai storage column create --model-uuid <contacts-uuid> \
  --column '{"slug":"email","type":"string","label":"Email","kind":"custom"}'

# 3. Set relationship: Contacts → Companies
cargo-ai storage relationship set \
  --from-model-uuid <contacts-uuid> \
  --to-model-uuid <companies-uuid>

# 4. Connection — create HubSpot connector
cargo-ai connection connector create \
  --integration-slug hubspot \
  --slug hubspot_prod \
  --name "HubSpot - Production"

# 5. AI — create and deploy scoring agent
cargo-ai ai agent create --name "Lead Scorer" --icon-color green --icon-face "📊"
cargo-ai ai release update-draft --agent-uuid <uuid> \
  --system-prompt "Score leads from 1–10 based on company fit." \
  --language-model-slug gpt-4o-mini \
  --temperature 0.0
cargo-ai ai release deploy-draft --agent-uuid <uuid> \
  --integration-slug openAi --language-model-slug gpt-4o-mini \
  --actions '[]' --resources '[]' --capabilities '[]' \
  --suggested-actions '[]' --mcp-clients '[]' \
  --description "Initial scoring agent"
```

***

## Chat with an AI agent

**Prompt:**

```
Ask the lead researcher agent to find the VP of Sales at Acme Corp.
```

```bash theme={null}
# 1. Find the agent
cargo-ai ai agent list
# → [{"uuid":"agent-uuid","name":"Lead Researcher"}]

# 2. Create a chat session
cargo-ai ai chat create \
  --trigger '{"type":"draft"}' \
  --agent-uuid <agent-uuid> \
  --name "Acme research"
# → {"chat":{"uuid":"chat-uuid",...}}

# 3. Send a message
cargo-ai ai message create \
  --chat-uuid <chat-uuid> \
  --parts '[{"type":"text","text":"Find the VP of Sales at Acme Corp and their LinkedIn URL."}]'
# → {"userMessage":{"uuid":"..."},"assistantMessage":{"uuid":"assistant-msg-uuid","status":"pending"}}

# 4. Poll for the response (every 2 seconds)
cargo-ai ai message get <assistant-msg-uuid>
# → Terminal when status is "success" — read .message.parts[].text

# 5. Continue the conversation (context is preserved in the chat)
cargo-ai ai message create \
  --chat-uuid <chat-uuid> \
  --parts '[{"type":"text","text":"Now find their email address."}]'
```

***

## Track credit usage

**Prompt:**

```
How many credits did the enrichment play consume last month, broken down by day?
```

```bash theme={null}
cargo-ai billing usage get-metrics \
  --from 2025-01-01 \
  --to 2025-01-31 \
  --workflow-uuid <enrichment-play.workflowUuid>
```

Group by connector to see which enrichment provider costs the most:

```bash theme={null}
cargo-ai billing usage get-metrics \
  --from 2025-01-01 \
  --to 2025-01-31 \
  --group-by connector_uuid
```

Check remaining credits:

```bash theme={null}
cargo-ai billing subscription get
# → {"subscription":{"plan":"self-serve","subscriptionAvailableCreditsCount":10000,"subscriptionCreditsUsedCount":3200,"resetAt":"2025-02-01T00:00:00Z"}}
# → Remaining: 10000 - 3200 = 6800 credits
```

<Note>
  Invoice amounts returned by `subscription get-invoices` are in cents. Divide
  by 100 for dollars.
</Note>

***

## Best practices

<AccordionGroup>
  <Accordion title="Verify authentication before every session">
    Run `cargo-ai whoami` and share the output with your agent if it seems confused about which workspace to target. If you work across multiple workspaces, make the active one explicit with `export CARGO_WORKSPACE_UUID=<uuid>`.
  </Accordion>

  <Accordion title="Front-load context about your workspace">
    Start a session by telling your agent what exists: *"I have Companies and
    Contacts models, a HubSpot connector, and a lead enrichment tool called
    'Enrich from Clearbit'."* This lets the agent confirm UUIDs rather than
    guessing, and saves multiple discovery round-trips.
  </Accordion>

  <Accordion title="Get the DDL before any SQL query">
    The table name for a Cargo model is not guessable. Always run `storage model get-ddl <uuid>` before writing queries. The DDL includes the exact table name (e.g., `datasets_default.models_companies`) and every column's type.
  </Accordion>

  <Accordion title="Ramp batch sizes gradually">
    Start every new workflow with 1 record, then 50, then 500, before running on
    your full segment. This surfaces connector rate limit issues before they
    affect thousands of records. Only connector nodes (`kind: "connector"`) have
    rate limits — native nodes do not.
  </Accordion>

  <Accordion title="Always inspect failedRunsCount after a batch">
    A batch reporting `status: "success"` can still have individual run failures. Check `failedRunsCount` in `batch get`, download failures with `run download --statuses error`, and re-queue with `batch create --data '{"kind":"recordIds","modelUuid":"<uuid>","ids":[...]}'`.
  </Accordion>

  <Accordion title="Keep a .cargo-context.md for repeat tasks">
    For frequently used workflows or segments, note their UUIDs in a `.cargo-context.md` in your project root. Your agent will use them directly instead of re-running discovery commands every session.

    ```markdown theme={null}
    # Cargo Workspace Context

    ## Models
    - Companies: `model-uuid-companies`
    - Contacts: `model-uuid-contacts`

    ## Key workflows
    - Lead Enrichment Tool: `workflow-uuid-enrichment`
    - MQL Scoring Play: `workflow-uuid-scoring`

    ## Connectors
    - HubSpot: `connector-uuid-hubspot`
    - Clearbit: `connector-uuid-clearbit`
    ```
  </Accordion>

  <Accordion title="Use --wait-until-finished for short operations">
    For quick runs (single records, small batches under 100 records), `--wait-until-finished` is the simplest pattern. For large batches (1000+ records), poll manually with `batch get` so your agent can report incremental progress without a timeout.
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup>
  <Card title="CLI Overview" icon="terminal" href="/cli/overview">
    Command reference, UUID flows, filter syntax, async patterns, and gotchas.
  </Card>

  <Card title="Cargo Skills on GitHub" icon="github" href="https://github.com/getcargohq/cargo-skills">
    Browse skill source, report issues, or contribute improvements.
  </Card>
</CardGroup>


# Cargo Skills
Source: https://docs.getcargo.ai/skills/overview

Run your GTM motion from Claude Code, Cursor, or Codex: build lead lists, find and verify emails, enrich companies and contacts, score leads, sync to your CRM, and watch buying signals like job changes and funding. 17 agent skills over the cargo-ai CLI, with provider costs and spend gates.

**Cargo Skills** turn the [Cargo CLI](/cli/overview) into something your AI agent
can drive on its own. Each skill is a prompt package that encodes the CLI's
commands, flags, UUID-discovery patterns, and gotchas — so instead of guessing,
your agent already knows exactly how to run tools, trigger plays, query the
warehouse, and deploy agents.

You just describe what you want:

```
"Trigger the MQL scoring play on all leads added this week."
  → cargo-ai orchestration play list
  → cargo-ai orchestration batch create --workflow-uuid <uuid> \
      --data '{"kind":"filter","modelUuid":"<uuid>"}' \
      --wait-until-finished
```

No manual UUID lookup, no documentation tab, no copy-pasting JSON.

<Note>
  Want to suggest an edit, report an issue, or fork the skills? Head to
  [getcargohq/cargo-skills](https://github.com/getcargohq/cargo-skills) on
  GitHub.
</Note>

***

## The skills

The set is one skill per [CLI command domain](/cli/overview#command-domains), plus
a `cargo` router that ties them together and a `cargo-gtm` outcome skill that
routes real-world GTM goals to the right capability skill:

| Skill                        | Domain      | What your agent can do                                                                                                                  |
| ---------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `cargo`                      | Router      | Overview of the whole skill set — the UUID flow between skills, async polling, end-to-end use cases, and common gotchas. Load it first. |
| `cargo-gtm`                  | Outcomes    | Front door for GTM goals — sourcing, waterfall enrichment, email/phone/LinkedIn lookup, verification, scoring, qualification, CRM sync  |
| `cargo-orchestration`        | Runtime     | Execute actions, run workflows, trigger batches, message AI agents, query runtime tables (runs/batches/spans/records) with SQL          |
| `cargo-storage`              | Schema      | Manage models, datasets, columns, and relationships; query workspace storage with SQL                                                   |
| `cargo-connection`           | Connectors  | List, create, update, and remove connectors; discover integrations and their available actions                                          |
| `cargo-ai`                   | Agents      | Create and configure agents, manage releases, connect MCP servers, and handle agent memories                                            |
| `cargo-content`              | Knowledge   | Upload and organize knowledge files, build native and connector-backed libraries for RAG                                                |
| `cargo-context`              | Context     | Inspect and edit the git-backed context knowledge base and run commands in its sandbox                                                  |
| `cargo-analytics`            | Measurement | Download workflow run results, export segment data, and monitor run metrics                                                             |
| `cargo-billing`              | Costs       | Pull usage metrics, check subscription status, view invoices, and manage credits                                                        |
| `cargo-hosting`              | Hosting     | Build, deploy, promote, and manage hosted apps (Vite SPAs) and edge workers                                                             |
| `cargo-workspace-management` | Admin       | Invite and manage users, create and rotate API tokens, organize resources into folders, inspect roles                                   |
| `cargo-project`              | Declarative | Declare the whole workspace as TypeScript and reconcile it — `project init`, `types`, `plan`, `deploy`, state and drift                 |

***

## 1. Install the CLI

Skills drive the CLI, so it has to be installed and authenticated first. Follow
the [Quickstart](/get-started/quickstart), then confirm:

```bash theme={null}
cargo-ai whoami
```

## 2. Install the skills

```bash theme={null}
npx skills add getcargohq/cargo-skills
```

This creates a `.skills/` directory with the Cargo skill files your agent reads
automatically. Commit it so every team member and CI environment shares the same
setup without a separate install step.

## 3. Verify

Ask your agent:

```
What Cargo skills do you have available?
```

It will list the available skills and what it can do with each.

***

## Supported agents & editors

Any tool that follows the [skills.sh](https://skills.sh) standard works with the
**same install command** — there's no per-editor configuration, because
`.skills/` is the universal integration point.

<CardGroup>
  <Card title="Claude Code" icon="anthropic">
    Persist your token in your shell profile so it's available from any working
    directory: `export CARGO_API_TOKEN=<your-api-token>` in `~/.zshrc` or
    `~/.bashrc`.
  </Card>

  <Card title="Cursor" icon="c">
    Run the install command in your project root; Cursor's agent picks up
    `.skills/` automatically.
  </Card>

  <Card title="Codex CLI" icon="terminal">
    Works out of the box once `.skills/` is present in the working directory.
  </Card>

  <Card title="GitHub Copilot (agent mode)" icon="github">
    Reads `.skills/` from the repository root — commit it so Copilot loads it in
    every session.
  </Card>

  <Card title="Windsurf" icon="wind">
    Same one-command install; no additional configuration required.
  </Card>

  <Card title="Any skills.sh agent" icon="robot">
    Follows the open [skills.sh](https://skills.sh) standard, so new compatible
    editors work with the same command.
  </Card>
</CardGroup>

***

## Troubleshooting

| Symptom                           | Fix                                                                                                                                                                                                  |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent says it has no Cargo skills | Run `npx skills add getcargohq/cargo-skills` in the project root and restart the session                                                                                                             |
| `cargo-ai: command not found`     | Run `npm install -g @cargo-ai/cli`                                                                                                                                                                   |
| `Unauthorized` errors             | Run `cargo-ai whoami` to confirm the active token and workspace                                                                                                                                      |
| Wrong workspace targeted          | Set `CARGO_WORKSPACE_UUID=<uuid>`, or sign in again for that workspace with `cargo-ai login --email <email> --workspace-uuid <uuid>` (an API token from `--token` stays pinned to its own workspace) |

***

## Next steps

<CardGroup>
  <Card title="Examples" icon="book-open" href="/skills/examples">
    Worked examples: run tools, trigger plays, query the warehouse, build
    workflows, deploy agents, and more.
  </Card>

  <Card title="CLI Overview" icon="terminal" href="/cli/overview">
    Command reference, UUID flows, filter syntax, async patterns, and gotchas.
  </Card>

  <Card title="Cargo Skills on GitHub" icon="github" href="https://github.com/getcargohq/cargo-skills">
    Browse skill source, report issues, or contribute improvements.
  </Card>

  <Card title="skills.sh standard" icon="book" href="https://skills.sh">
    Learn how skills work and how to author your own packages.
  </Card>
</CardGroup>


# Capacities
Source: https://docs.getcargo.ai/territories/capacities

Cap how many records each member receives within a time window — with fixed limits, expiring windows, or limits derived from a data model.

A **capacity** is a workload limit you attach to an [Allocate](/workflows/overview) node. It counts how many records each [member](/territories/members) has already received and marks anyone at their limit as unavailable, so [territory](/territories/territories) round-robin skips them and leads flow to reps with headroom.

## Anatomy of a capacity

| Field                                      | Description                                                                       |
| ------------------------------------------ | --------------------------------------------------------------------------------- |
| `name`                                     | Human-readable name (e.g. `AE Capacity`).                                         |
| `color`                                    | Visual tag: `orange`, `red`, `purple`, `green`, `yellow`, or `grey`.              |
| `description`                              | Optional free-text note.                                                          |
| `memberCapacity`                           | Max distinct records a member can hold in the current window. `null` = unlimited. |
| `allocationExpirationPolicy`               | How the counting window resets (see below). `null` = allocations never expire.    |
| `modelUuid`                                | Optional data model to derive existing allocations from (model-based capacity).   |
| `filter`, `idColumnSlug`, `timeColumnSlug` | Required when `modelUuid` is set — how to read records from that model.           |

## Limit types

### Fixed limit

Set `memberCapacity` to the number of records each member may hold. Once a member reaches it, they're skipped until an allocation expires (or forever, if there's no expiration policy). Leave it `null` for no limit.

### Expiring windows

`allocationExpirationPolicy` controls when past allocations stop counting, so a member's capacity refills over time. The interval can be:

`hourly`, `daily`, `weekly`, `monthly`, `quarterly`, `yearly`, or `null` (never expires).

Each interval works in one of two ways:

* **Sliding** — a rolling window (e.g. the last 24 hours for `daily`). This is the default.
* **Fixed boundary** — the window resets at a set point (e.g. every day at `09:00` UTC, or every Monday). Fixed boundaries take extra fields such as `time` (UTC `HH:MM`), `weekDay` (`1`=Monday … `7`=Sunday), `day`, `month`, or `minute` depending on the interval.

<Note>
  A member's used capacity is the count of **distinct record IDs** allocated to
  them within the current window — re-allocating the same record doesn't double-count.
</Note>

### Model-based capacity

Instead of counting only Cargo's own allocations, a capacity can derive existing workload from a [data model](/models/overview) — for example, counting each rep's open opportunities. Set `modelUuid` and provide:

| Field            | Purpose                                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| `filter`         | Segmentation filter selecting the relevant rows (e.g. open deals), including which member owns each row. |
| `idColumnSlug`   | Column used as the record ID.                                                                            |
| `timeColumnSlug` | Date column used as the allocation timestamp (for expiration windows).                                   |

Cargo syncs those rows into allocation counts, matching each row's owner to a member. A sync runs automatically when the linked model emits new data (and can also be triggered via the API); the capacity records when it last synced. At allocation time, both the synced historical counts and any new allocations made since the last sync are added together to decide availability.

## Manage capacities from the CLI

```bash theme={null}
cargo-ai revenue-organization capacity list
cargo-ai revenue-organization capacity get <uuid>

# Simple, expiring capacity
cargo-ai revenue-organization capacity create \
  --name "AE Capacity" --color purple \
  --member-capacity 50 \
  --allocation-expiration-policy daily

# Model-based capacity
cargo-ai revenue-organization capacity create \
  --name "Open deals cap" --color green \
  --member-capacity 20 \
  --model-uuid "<model-uuid>" \
  --id-column-slug "record_id" \
  --time-column-slug "created_at" \
  --filter '{ ... }'

cargo-ai revenue-organization capacity update \
  --uuid "<uuid>" --member-capacity 75

cargo-ai revenue-organization capacity remove <uuid>
```

| Command  | Required            | Optional                                                                                                                                                          |
| -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create` | `--name`, `--color` | `--description`, `--member-capacity`, `--allocation-expiration-policy`, `--model-uuid`, `--id-column-slug`, `--time-column-slug`, `--filter`                      |
| `update` | `--uuid`            | `--name`, `--color`, `--description`, `--member-capacity`, `--allocation-expiration-policy`, `--model-uuid`, `--id-column-slug`, `--time-column-slug`, `--filter` |

<Note>
  Segmentation `--filter` JSON uses the `conjonction` key (Cargo's intentional
  spelling). When `--model-uuid` is set, `--filter`, `--id-column-slug`, and
  `--time-column-slug` are required.
</Note>

## Apply a capacity during allocation

A capacity does nothing on its own — attach its `capacityUuid` to an **Allocate** node. Whichever allocation mode you use (`territory`, `members`, `email`, or `matching`), members at their limit are marked unavailable and skipped; if everyone is full, the [fallback member](/territories/territories) receives the lead.

<CardGroup>
  <Card title="Territories" icon="map" href="/territories/territories">
    Group members into pools that leads are distributed across.
  </Card>

  <Card title="Build a play" icon="play" href="/plays/overview">
    Add an Allocate step that enforces capacity limits.
  </Card>
</CardGroup>


# Members
Source: https://docs.getcargo.ai/territories/members

The sales reps that leads are distributed to — imported from your CRM and enriched with routing metadata like languages and specializations.

A **member** is a person on your revenue team who can receive leads. Members are the atoms of the whole system: [territories](/territories/territories) are pools of members, [capacities](/territories/capacities) cap how much each member can hold, and an [Allocate](/workflows/overview) node ultimately hands each lead to a single member.

## Where members come from

Members are imported from a connected CRM rather than created by hand, so your Cargo team hierarchy stays in step with the source of truth in [Salesforce](/integration/salesforce), [HubSpot](/integration/hubspot), or another connector. Syncing pulls in each rep and keeps their details current; reps removed in the CRM stop receiving leads on the next sync.

Social selling connectors sync members too: [LinkedIn](/integration/linkedin) and [Sales Navigator](/integration/sales-navigator) contribute one member per teammate who has connected their LinkedIn session through the Chrome extension. That lets a capacity cap LinkedIn activity — connection requests, messages, profile visits — per rep, the same way it caps CRM records.

<Note>
  Connect and configure your CRM first — Revenue Organization has no members to
  route to until a connector has synced your team in.
</Note>

## Anatomy of a member

| Field            | Description                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `uuid`           | Cargo's stable identifier — the value you reference in a territory's `members` array.                             |
| `name` / `email` | Identity, synced from the CRM.                                                                                    |
| `crmUserId`      | The originating record in the connected CRM, used to write assignments back.                                      |
| `mailboxes`      | Cargo mailboxes attached to this member. A member can hold many; each mailbox belongs to at most one member.      |
| `metadata`       | Custom attributes like languages, specializations, or region that you can branch on upstream of an Allocate node. |

## Manage members from the CLI

```bash theme={null}
# Pull the latest team from a connector
cargo-ai revenue-organization member sync --connector-uuid <uuid>

# List members (and grab the UUIDs you reference in territories)
cargo-ai revenue-organization member list

# Attach Cargo mailboxes to a member (empty --mailbox-uuids detaches all)
cargo-ai revenue-organization member update --uuid <uuid> --mailbox-uuids <mailbox-uuid>
```

<Note>
  `member list` is how you get the member UUIDs used in `territory create   --members` and in fallback-member fields — sync first, then list.
</Note>

## Next steps

<CardGroup>
  <Card title="Territories" icon="map" href="/territories/territories">
    Group members into pools and distribute leads across them.
  </Card>

  <Card title="Capacities" icon="gauge" href="/territories/capacities">
    Cap how many records each member receives within a time window.
  </Card>

  <Card title="Salesforce integration" icon="cloud" href="/integration/salesforce">
    Connect your CRM to import team members automatically.
  </Card>

  <Card title="Build a play" icon="play" href="/plays/overview">
    Create workflows that trigger lead allocation.
  </Card>
</CardGroup>


# Overview
Source: https://docs.getcargo.ai/territories/overview

Model your sales team structure and automate lead distribution across territories and capacities

Revenue Organization in Cargo provides a complete system for managing your sales team structure and automating lead distribution. It keeps your team hierarchy synchronized with your CRM while giving you fine-grained control over how leads flow to the right reps.

***

## Core concepts

Revenue Organization consists of three interconnected components that work together to route leads intelligently:

| Concept                                     | Description                                                                                                               |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **[Members](/territories/members)**         | Your sales team imported from connected CRMs, enriched with custom metadata like languages and specializations.           |
| **[Territories](/territories/territories)** | Named pools of members that leads are distributed across with weighted round-robin—each with an optional fallback member. |
| **[Capacities](/territories/capacities)**   | Workload limits that ensure fair distribution and prevent rep overload.                                                   |

***

## How it works

```mermaid theme={null}
flowchart LR
    A[New Lead] --> B[Allocation Node]
    B --> C{Match Rules}
    C --> D[Territory]
    C --> E[Email Domain]
    C --> F[Connector Match]
    D --> G[Available Rep]
    E --> G
    F --> G
    G --> H[CRM Assignment]
```

1. **Leads enter** through a play trigger
2. **Matching rules** determine which reps are eligible
3. **Capacity checks** filter to available team members
4. **Round-robin** distributes evenly among eligible reps
5. **Assignment syncs** back to your CRM

***

## Key features

| Feature                  | Description                                                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| **CRM sync**             | Team members automatically import and stay synchronized with Salesforce, HubSpot, or other connected CRMs |
| **Territory routing**    | Route leads based on geographic regions, industry verticals, or company size segments                     |
| **Capacity management**  | Set daily, weekly, or custom limits per rep to balance workloads                                          |
| **Fallback rules**       | Ensure every lead gets assigned, even when primary routing fails                                          |
| **Allocation history**   | Full audit trail of every assignment with links to the triggering play run                                |
| **Model-based capacity** | Calculate availability from real pipeline data like open deals                                            |

***

## When to use Revenue Organization

<AccordionGroup>
  <Accordion title="You have multiple sales reps">
    Any team with more than one rep benefits from automated routing. Even simple round-robin distribution eliminates manual assignment work.
  </Accordion>

  <Accordion title="You need territory-based routing">
    Geographic, vertical, or segment-based sales structures require rules that match leads to the right territory before assignment.
  </Accordion>

  <Accordion title="You want to balance workloads">
    Capacity limits prevent top performers from being overloaded while ensuring all reps receive fair lead distribution.
  </Accordion>

  <Accordion title="You need assignment audit trails">
    Compliance, optimization, or troubleshooting all benefit from knowing exactly when, why, and how each lead was assigned.
  </Accordion>
</AccordionGroup>

***

## Getting started

<Steps>
  <Step title="Connect your CRM">
    Revenue Organization imports team members from your connected CRM. Make sure your [Salesforce](/integration/salesforce) or [HubSpot](/integration/hubspot) integration is configured.
  </Step>

  <Step title="Define territories">
    Group your members into territories that reflect your sales structure—by region, vertical, or any custom segmentation.
  </Step>

  <Step title="Set capacities">
    Configure workload limits to ensure fair distribution. Start conservative and adjust based on actual throughput.
  </Step>

  <Step title="Add allocation to a play">
    Route leads through your revenue organization rules with an allocation step
    in a [play](/plays/overview).
  </Step>
</Steps>

## From the CLI

The whole revenue-organization domain is scriptable from the CLI (there are no `define*` builders for it yet):

```bash theme={null}
cargo-ai revenue-organization member list
cargo-ai revenue-organization territory create \
  --label "West" --color orange \
  --members '[{"uuid":"<member-uuid>","weight":1}]'
cargo-ai revenue-organization capacity create --name "AE Capacity" --color purple
cargo-ai revenue-organization allocation list
```

<Note>
  Lead allocation itself is currently configured as a step in the visual play
  editor (the **Allocate** node) — see [Workflows](/workflows/overview) for the
  code vs. canvas coverage.
</Note>

***

## Next steps

<CardGroup>
  <Card title="Members" icon="users" href="/territories/members">
    Import your team from a CRM and enrich them with routing metadata.
  </Card>

  <Card title="Territories" icon="map" href="/territories/territories">
    Group members into pools and distribute leads across them.
  </Card>

  <Card title="Capacities" icon="gauge" href="/territories/capacities">
    Cap how many records each member receives within a time window.
  </Card>

  <Card title="Using the UI" icon="table-cells" href="/territories/using-ui">
    Build territories, capacities, and allocation from the workspace.
  </Card>
</CardGroup>


# Territories
Source: https://docs.getcargo.ai/territories/territories

Group members into named pools and distribute leads across them with weighted round-robin — the building block Allocate nodes route leads to.

A **territory** is a named group of [members](/territories/members) that leads can be distributed across. When an [Allocate](/workflows/overview) node routes a lead to a territory, Cargo picks one of its members with **weighted round-robin** — spreading assignments evenly (or proportionally, if you set weights) and skipping anyone who is unavailable.

<Note>
  Territories don't encode region, vertical, or segment rules themselves. They're
  a pool of members plus distribution weights. To route different leads to
  different territories, branch upstream in your [workflow](/workflows/overview)
  and point each Allocate node at the right `territoryUuid`.
</Note>

## Anatomy of a territory

| Field                | Description                                                                 |
| -------------------- | --------------------------------------------------------------------------- |
| `label`              | Human-readable name (e.g. `West`, `Enterprise EMEA`).                       |
| `color`              | Visual tag: `orange`, `red`, `purple`, `green`, `yellow`, or `grey`.        |
| `description`        | Optional free-text note.                                                    |
| `members`            | The pool of members, each with an optional `weight`.                        |
| `fallbackMemberUuid` | Optional member who receives the lead when no one in the pool is available. |

Each entry in `members` is a member `uuid` plus an optional `weight`:

```json theme={null}
[
  { "uuid": "<member-uuid>", "weight": 2 },
  { "uuid": "<member-uuid>", "weight": 1 }
]
```

## How distribution works

When an Allocate node targets a territory, Cargo runs weighted round-robin over the pool:

* **`weight: 1` (or `null`)** — a normal share of leads. A missing weight is treated as `1`.
* **`weight: 2`, `3`, …** — proportionally more leads than lower-weighted members.
* **`weight: 0`** — excluded from the pool entirely (no leads).
* **Unavailable members** — anyone filtered out by a [capacity](/territories/capacities) is skipped for that assignment.

Members are ordered deterministically and the rotation position is persisted, so distribution stays even across separate play runs rather than restarting each time.

### Fallback member

If every eligible member is unavailable (all at capacity, or all weighted `0`), the lead goes to the `fallbackMemberUuid` and the resulting allocation is flagged as a fallback assignment. If no fallback is set, allocation fails with a "no members available" error — so set a fallback whenever every lead must land somewhere.

## Manage territories from the CLI

```bash theme={null}
cargo-ai revenue-organization territory list
cargo-ai revenue-organization territory get <uuid>

cargo-ai revenue-organization territory create \
  --label "West" --color orange \
  --members '[{"uuid":"<member-uuid>","weight":1}]' \
  --description "West-coast AEs" \
  --fallback-member-uuid "<member-uuid>"

cargo-ai revenue-organization territory update \
  --uuid "<uuid>" \
  --members '[{"uuid":"<member-uuid>","weight":2}]'

cargo-ai revenue-organization territory remove <uuid>
```

| Command  | Required                          | Optional                                                                     |
| -------- | --------------------------------- | ---------------------------------------------------------------------------- |
| `create` | `--label`, `--color`, `--members` | `--description`, `--fallback-member-uuid`                                    |
| `update` | `--uuid`                          | `--label`, `--color`, `--description`, `--members`, `--fallback-member-uuid` |

<Note>
  Members are CRM-synced — run `cargo-ai revenue-organization member sync   --connector-uuid <uuid>` and `member list` to get the member UUIDs you
  reference in `--members`.
</Note>

## Route leads to a territory

Territories are consumed by the **Allocate** node in a play. Select the `territory` mode, choose the `territoryUuid`, and (optionally) attach a [capacity](/territories/capacities) to cap each member's workload.

<CardGroup>
  <Card title="Capacities" icon="gauge" href="/territories/capacities">
    Cap how many records each member can receive within a time window.
  </Card>

  <Card title="Build a play" icon="play" href="/plays/overview">
    Add an Allocate step that distributes leads across your territory.
  </Card>
</CardGroup>


# Using UI
Source: https://docs.getcargo.ai/territories/using-ui

Build territories and capacities in the workspace and route leads to them with an Allocate node — no code required.

Everything in Revenue Organization can be configured from the CLI, but the day-to-day workflow — grouping reps into territories, setting workload limits, and wiring allocation into a play — is built visually in the workspace. This page walks through that end-to-end.

## What you'll build

A working lead-distribution setup: a **territory** of reps, a **capacity** that caps each rep's workload, and a play with an **Allocate** node that routes incoming leads across them.

***

## Step-by-step

### Step 1: Sync your team

Revenue Organization routes to [members](/territories/members) imported from a CRM. Make sure your [Salesforce](/integration/salesforce) or [HubSpot](/integration/hubspot) connector is configured, then sync so your reps appear as members.

<Note>
  No members means nothing to route to — connect and sync your CRM before
  building territories.
</Note>

### Step 2: Create a territory

1. Open **Revenue Organization** in your Cargo workspace sidebar
2. Go to **Territories** and click **+ New Territory**
3. Give it a **label** (e.g. `West`, `Enterprise EMEA`) and pick a **color**
4. Add members to the pool and set an optional **weight** on each — higher weights receive proportionally more leads
5. Optionally set a **fallback member** to catch leads when everyone else is unavailable

See [Territories](/territories/territories) for how weighted round-robin distributes across the pool.

### Step 3: Set a capacity

1. Go to **Capacities** and click **+ New Capacity**
2. Name it (e.g. `AE Capacity`) and set a **member capacity** — the max records each rep can hold
3. Choose an **expiration policy** if the limit should refill over time (hourly, daily, weekly, …)
4. For a limit derived from live pipeline data, point the capacity at a [data model](/models/overview) instead of a fixed number

See [Capacities](/territories/capacities) for fixed, expiring, and model-based limits.

### Step 4: Add an Allocate node to a play

1. Open (or create) a [play](/plays/overview) and add an **Allocate** node
2. Choose the `territory` mode and select the territory you built
3. Attach your capacity so members at their limit are skipped
4. Connect the node so leads flow into it from your trigger

<Note>
  The Allocate node lives in the visual play editor. See
  [Workflows](/workflows/overview) for how it fits alongside the other nodes.
</Note>

### Step 5: Test and monitor

Run the play with a sample lead and confirm it lands on the expected rep. Every assignment is recorded with a full allocation history — including fallback assignments — so you can audit exactly when, why, and to whom each lead was routed.

***

## Next steps

<CardGroup>
  <Card title="Members" icon="users" href="/territories/members">
    Import your team from a CRM and enrich them with routing metadata.
  </Card>

  <Card title="Territories" icon="map" href="/territories/territories">
    Group members into pools and distribute leads across them.
  </Card>

  <Card title="Capacities" icon="gauge" href="/territories/capacities">
    Cap how many records each member receives within a time window.
  </Card>

  <Card title="Build a play" icon="play" href="/plays/overview">
    Add an Allocate step that distributes leads across your territory.
  </Card>
</CardGroup>


# Triggering from Salesforce
Source: https://docs.getcargo.ai/tools/embed-in-crm

Create a custom button inside the native Salesforce app in order to trigger the tool directly from within the CRM.

This integration enables your sales reps to autonomously launch Cargo actions directly associated to a contact or account without leaving the CRM. Perfect for on-demand company research, contact enrichment, and lead scoring.

***

## Prerequisites

What you'll need to make this possible:

| Requirement                 | Description                                                                                                                         |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| **Salesforce admin access** | Required to create flows, named credentials, and custom buttons—and to create the SFDC connector in Cargo (if not already the case) |
| **Cargo workspace**         | With write access and a Tool already configured                                                                                     |
| **API access**              | Your Cargo API token and tool endpoint URL                                                                                          |

***

## Step 1 - Define and deploy a Tool in Cargo

Define the tool in code — an input schema that matches the fields Salesforce will send, a workflow that researches the account and writes back via the Salesforce connector, then deploy it:

```ts tools/account-research.ts theme={null}
import { defineTool, defineWorkflow, connectorRef } from "@cargo-ai/cdk";
import { z } from "zod";

const research = defineWorkflow(
  "account-research",
  {
    input: z.object({ accountId: z.string(), domain: z.string(), ownerId: z.string() }),
    output: z.object({ message: z.string() }),
    uses: { salesforce: connectorRef("9c26…", "salesforce") },
  },
  ({ input, ai, uses }) => {
    const brief = ai(`Research the company at ${input.domain} for account ${input.accountId}.`);
    uses.salesforce.updateRecords({
      objectType: "Account",
      matchingValue: input.accountId,
      matchingPropertyName: "Id",
      mappings: [{ propertyName: "Research__c", value: brief }],
    });
    return { message: brief };
  },
);

export const accountResearch = defineTool("account-research", { workflow: research });
```

```bash theme={null}
cargo-ai project deploy
cargo-ai orchestration tool list        # → the tool's UUID for the URL below
```

<Accordion title="Prefer the UI?">
  Build the same tool in the visual editor — an AI prompt for research, a
  Salesforce **Update** action, and input parameters for the fields Salesforce
  sends.

  <div>
    <iframe title="Integrate Account Research Workflows with API Access" />
  </div>
</Accordion>

Either way, the tool is reachable at its execute endpoint — this is the URL Salesforce will call:

```bash theme={null}
https://api.getcargo.io/v1/tools/<TOOL_UUID>/execute?token=<API_TOKEN>
```

| Placeholder   | Description          |
| :------------ | :------------------- |
| `<TOOL_UUID>` | Your unique tool ID  |
| `<API_TOKEN>` | Your Cargo API token |

***

## Step 2 - Create a named credential

Named credentials store the Cargo API endpoint securely within Salesforce.

<div>
  <iframe title="Step 2 - Create a Named Credential in Salesforce" />
</div>

1. Go to **Setup → Named Credentials**
2. Click **New** and select **Legacy Named Credential**
3. Enter the label and URL for your Cargo endpoint
4. Save the credential

***

## Step 3 - Register an external service

External services allow Salesforce to communicate with the Cargo API. In **Setup → External Services**, register a new service.

<div>
  <iframe title="Step 3 - Register an External Service in Salesforce" />
</div>

Select the named credential you just created and register the service with the following OpenAPI schema:

```json theme={null}
{
  "openapi": "3.0.1",
  "info": {
    "title": "Cargo",
    "description": ""
  },
  "paths": {
    "CARGOPATH": {
      "post": {
        "description": "",
        "operationId": "Query Cargo",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "description": "",
            "required": false,
            "allowEmptyValue": false,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accountId": { "type": "string" },
                  "linkedinUrl": { "type": "string" },
                  "domain": { "type": "string" },
                  "name": { "type": "string" },
                  "linkedinId": { "type": "string" },
                  "ownerId": { "type": "string" }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

<Warning>
  **Replace `CARGOPATH`** with your actual Tool URL from Cargo. Use only the path portion starting with `/v1` and ending with `execute`:

  ```
  /v1/tools/e276dc32-aca1-4136-bbe7-dce879346c58/execute
  ```
</Warning>

<Note>
  The `properties` in the schema must match the fields you'll configure in **Step 4.2**. For example:

  ```json theme={null}
  {
    "ownerId": { "type": "string" },
    "accountId": { "type": "string" },
    "domain": { "type": "string" }
  }
  ```
</Note>

***

## Step 4 - Create a flow

Flows orchestrate the entire integration—retrieving data from Salesforce, sending it to Cargo, and handling the response.

### 4.1 - Retrieve account records

Create a **flow** that pulls account records from Salesforce.

<div>
  <iframe title="Step 3 - Create a Flow to Retrieve Account Records in Salesforce" />
</div>

### 4.2 - Map fields in an assignment step

Map the Salesforce fields to the inputs required by your Cargo HTTP call.

<div>
  <iframe title="Step 4 - Map Fields in a Salesforce Flow Assignment Step" />
</div>

Specify the JSON schema for the HTTP callout—this must align with the schema from **Step 3**. Use placeholder values to configure the action:

```json theme={null}
{
  "accountId": "0018b00002ABCDeAA1",
  "domain": "example.com",
  "ownerId": "0058b00001XYZAbAA1"
}
```

### 4.3 - Add a screen step at the end of the flow

Add a **screen element** to display results or request user input before the flow completes.

<div>
  <iframe title="Step 5 - Add a Screen Step to Your Salesforce Flow" />
</div>

### 4.4 - Map HTTP callout variables to the assignment action

Connect the variables created during the HTTP callout configuration to your assignment action. This ensures data flows correctly through the flow.

<div>
  <iframe title="Step 4.4 - Configure Variable Assignments for HTTP Callouts in Salesforce Flow" />
</div>

***

## Step 5 - Add a custom button to your Accounts interface

Finally, create the button that sales reps will use to trigger the flow. Go to **Setup → Object Manager → Account → Buttons, Links, and Actions**.

<div>
  <iframe title="Step 6 - Add a Custom Flow Button to an Account in Salesforce" />
</div>

1. Create a new **Flow Button**
2. Link it to the flow you built in Step 4
3. Add the button to the Account page layout

***

## Testing your integration

### Verify the setup

1. **Test the button** — Click your custom button on an Account record
2. **Check the flow** — Ensure the flow runs without errors
3. **Monitor the Tool** — Verify the Cargo Tool executes and updates the Salesforce record
4. **Review results** — Confirm the Account record is updated with the research data

### Troubleshooting

<AccordionGroup>
  <Accordion title="Flow failed to start">
    * Check that the custom button is properly linked to the flow - Verify the
      flow is active and has the correct permissions
  </Accordion>

  <Accordion title="HTTP callout failed">
    * Verify the named credential is correctly configured - Check that the API
      token is valid and has proper permissions - Ensure the tool ID in the URL
      matches your Cargo tool
  </Accordion>

  <Accordion title="Tool not executing">
    * Confirm the tool is receiving data from Salesforce - Check that the Tool
      is active and properly configured - Verify the Salesforce update action has
      the correct field mappings
  </Accordion>
</AccordionGroup>

***

## Next steps

Once your integration is working:

| Action               | Description                                    |
| :------------------- | :--------------------------------------------- |
| **Train your team**  | Show reps how to use the new button            |
| **Monitor usage**    | Track which accounts are being researched      |
| **Optimize prompts** | Refine your Tool's AI prompts based on results |
| **Scale up**         | Add similar buttons for Contacts or Leads      |


# Monitoring a tool
Source: https://docs.getcargo.ai/tools/monitoring

Inspect runs, pull metrics, re-queue failures, and set alerts from the CLI — or the UI

Every run a tool produces is queryable from the CLI, so you can monitor health, compute error rates, and re-queue failures from a terminal or CI job. The same data backs the **Records** and **Metrics** views in the UI.

## Inspect runs from the CLI

```bash theme={null}
cargo-ai orchestration tool list                       # → workflowUuid

# List recent runs, optionally filtered by status
cargo-ai orchestration run list \
  --workflow-uuid <uuid> \
  --statuses error \
  --created-after 2025-01-12

# Drill into one run — inputs, node-by-node outputs, timings, errors
cargo-ai orchestration run get <run-uuid>
```

Run statuses are `running`, `success`, `error`, and `cancelled`.

## Metrics

Pull per-node execution counts and credit usage over a date range:

```bash theme={null}
cargo-ai orchestration run get-metrics \
  --workflow-uuid <uuid> \
  --created-after 2025-01-12 \
  --created-before 2025-01-19
```

```json theme={null}
{
  "runMetrics": [
    {
      "nodeUuid": "enrich-node-uuid",
      "totalExecutionsCount": 1000,
      "successExecutionsCount": 950,
      "errorExecutionsCount": 48,
      "cancelledExecutionsCount": 2,
      "creditsUsedCount": 450
    }
  ]
}
```

Error rate per node = `errorExecutionsCount / totalExecutionsCount` (here `48 / 1000 = 4.8%`).

## Re-queue failed runs

Download the failed runs, extract their record IDs, and re-run only those:

```bash theme={null}
# 1. Download failures
cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --statuses error \
  --created-after 2025-01-12 > failed_runs.json

# 2. Re-run just the failed records
RECORD_IDS=$(jq '[.[].recordId]' failed_runs.json)
cargo-ai orchestration batch create \
  --workflow-uuid <uuid> \
  --data "{\"kind\":\"recordIds\",\"recordIds\":$RECORD_IDS}"
```

<Tip>
  Before re-queuing, check whether failures are transient (rate limits) or
  permanent (invalid data). Fix permanent issues first — retrying won't help.
</Tip>

## From the UI

The tool editor's **Records** view lists the same runs with status filters (by batch, version, status, date, node outcome); click a run for the node-by-node breakdown. The **Metrics** view charts success rate, latency (p50/p95/p99), volume, and error distribution, grouped by batch, version, or date. Failed runs can be retried individually or in bulk from Records.

<iframe title="Retrying a failed run" />

## Alerts

To be notified when a tool's error rate, latency, or credit burn crosses a line, define an [alert](/alerts/overview) scoped to its workflow — it evaluates on a cron and fires actions (a Slack message, an [HTTP](/integration/http) call, a tool, or an agent) on breach. That is a **threshold over a window**, not a webhook per failed run.

To POST to your own systems, add an HTTP Call as one of those actions. There is no fixed Cargo payload — you write the body, and Cargo interpolates the firing into it:

```ts theme={null}
{
  ref: http.actions.call,
  config: {
    url: "https://your-server.com/alerts",
    method: "post",
    bodyFormat: "json",
    bodyJson: `{
      "alert": "{{alert.name}}",
      "url": "{{alert.url}}",
      "value": "{{event.value}}",
      "threshold": "{{event.threshold}}",
      "operator": "{{event.operator}}",
      "windowStart": "{{event.windowStart}}",
      "windowEnd": "{{event.windowEnd}}",
      "spansUrl": "{{event.spansUrl}}"
    }`,
  },
}
```

The full variable list is under [Actions](/alerts/overview#actions-what-fires-on-breach). Slack and email are the same mechanism — a Slack `postMessage` or Resend/SendGrid `sendEmail` action on the alert.

For a callback when a batch you started via the API finishes (success or error), pass `webhookUrl` on the batch instead — see [Triggering](/tools/triggering#batch-execution).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tool execution times out">
    Break complex tools into smaller ones, add timeouts to slow external calls,
    reduce batch sizes, or use async execution for long-running operations.
  </Accordion>

  <Accordion title="Rate limit errors from integrations">
    Only connector nodes (`kind: "connector"`) are rate-limited. Add delays
    between calls, distribute load, reduce concurrency, or check the
    integration's documented limits.
  </Accordion>

  <Accordion title="Data not found in enrichment">
    Verify the input format (e.g. domain without `https://`), confirm the record
    exists in the provider's database, and add fallback providers or validation
    before the enrichment step.
  </Accordion>

  <Accordion title="CRM write failures">
    Confirm the record exists first, check field permissions and required
    fields, validate data types against CRM field types, and watch for
    duplicate-detection rules.
  </Accordion>
</AccordionGroup>

## Best practices

* **Set alerts before production** — don't wait for users to report issues.
* **Review metrics regularly** — spot trends before they become incidents.
* **Fix root causes** — investigate repeated failures instead of blindly retrying.
* **Version changes** — correlate performance shifts with deploys.


# Overview
Source: https://docs.getcargo.ai/tools/overview

Reusable, single-purpose automations backed by a workflow. Define them with defineTool and call them from plays, agents, MCP servers, or the API.

A **tool** is a reusable automation with typed inputs and outputs — enrich a contact, score a lead, find stakeholders. Once deployed, a tool can be triggered on demand, run inside plays, called by agents, exposed over MCP, or invoked via the API.

## Define a tool

A tool is backed by a [workflow](/workflows/overview). `defineWorkflow` compiles the logic; `defineTool` creates the tool and deploys that workflow as its release.

```ts tools/enrich.ts theme={null}
import { defineTool, defineWorkflow } from "@cargo-ai/cdk";
import { z } from "zod";
import { enricher } from "../agents/enricher";

const enrichFlow = defineWorkflow(
  "enrich-contact",
  {
    input: z.object({ email: z.string() }),
    output: z.object({ company: z.string(), enriched: z.boolean() }),
    uses: { enricher },
  },
  ({ input, uses }) => {
    // An agent call resolves to `{ answer, evaluation? }` — read `.answer`.
    const company = uses.enricher({
      prompt: `Which company owns the email domain of ${input.email}?`,
    }).answer;
    return { company, enriched: true };
  },
);

export const enrich = defineTool("enrich", {
  workflow: enrichFlow,
  description: "Enrich a contact with firmographic data.",
  emojiSlug: "mag",
  triggers: [{ cron: "0 9 * * 1", name: "Weekly enrichment" }],
});
```

## Deploy and run

```bash theme={null}
cargo-ai project deploy                              # deploy the tool + its workflow
cargo-ai orchestration tool list                 # → workflowUuid
cargo-ai orchestration run create \
  --workflow-uuid <uuid> \
  --data '{"email":"ada@acme.com"}' \
  --wait-until-finished
```

## Where tools run

| Context           | How                                                                           |
| ----------------- | ----------------------------------------------------------------------------- |
| **On demand**     | `cargo-ai orchestration run create`, or the Trigger tab                       |
| **In a play**     | reference it in a workflow via `uses`                                         |
| **From an agent** | list it in the agent's `tools`                                                |
| **Over MCP**      | include it in `defineMcpServer`                                               |
| **Public form**   | expose the tool as an embeddable form — see [Public form](/tools/public-form) |
| **API**           | `POST /v1/tools/{id}/execute`                                                 |

## Learn more

<CardGroup>
  <Card title="Workflows" icon="diagram-project" href="/workflows/overview">
    The DSL that backs every tool.
  </Card>

  <Card title="Triggering" icon="bolt" href="/tools/triggering">
    Single runs, bulk runs, plays, agents, MCP, and the API.
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/tools/monitoring">
    Records, metrics, retries, and alerts.
  </Card>

  <Card title="Using the UI" icon="mouse-pointer" href="/tools/using-ui">
    Build the same tool in the visual editor.
  </Card>
</CardGroup>


# Public form
Source: https://docs.getcargo.ai/tools/public-form

Expose a tool as a public, embeddable form that runs the tool's workflow on submit

The **public form** turns a tool into a hosted, embeddable web form. Visitors fill it in on your site, and each submission runs the tool's workflow — like a Typeform that triggers a Cargo automation instead of just collecting data.

It is the easiest way to put a tool behind a public surface (landing page, in-product survey, partner site) without writing a backend.

<iframe title="Embed a tool as a public form" />

***

## How it works

Every tool already has an **Input** node that defines its data schema (see [Tools overview](/tools/overview)). When the public form is enabled, Cargo hosts a zero-dependency SDK (`@cargo-ai/form-sdk`) that reads those input fields and renders them as a styled form on your page. Each submission runs the same workflow that the **Trigger** tab, plays, and agents run — only the entry point changes.

<Note>
  The tool **must be published** for the public form to accept submissions. The
  form always renders the deployed version, not the working draft.
</Note>

***

## Enabling the public form

Declare the public form on the tool in code — it deploys with `cargo-ai project deploy` alongside everything else:

```ts tools/enrich.ts theme={null}
import { defineTool, env } from "@cargo-ai/cdk";

export const enrich = defineTool("enrich", {
  workflow: enrichFlow,
  publicForm: {
    isEnabled: true,
    allowedOrigins: ["https://www.acme.com"],   // exact origins; "*" for fully public
    spam: {
      captchaProvider: "turnstile",             // or "hcaptcha" / null
      captchaSiteKey: "YOUR_SITE_KEY",
      captchaSecret: env("TURNSTILE_SECRET"),
      minFillMillis: 1500,                       // time-trap; 0 disables it
    },
    presentation: null,                          // workspace default theme — see Appearance below
  },
});
```

<Note>
  `captchaSecret` is a plain string in the config (not an encryption field), so
  `secret()` doesn't apply here — use `env()` to keep the value out of your
  repo while still deploying it.
</Note>

Every field below (access, spam protection, appearance) maps to a key in this `publicForm` config. After deploy, grab the embed snippet from the tool and drop it into your page.

<Accordion title="Prefer the UI?">
  Open your tool → **Trigger** tab → **Public form** → **Configure**, toggle
  **Enable public form** on, set access / spam / appearance, and save. The
  **Embed snippet** section then gives you a ready-to-paste `<script>` tag.
</Accordion>

***

## Access

### Allowed origins

The form is gated by an explicit allow-list of browser origins. Requests from any other origin are rejected with `403`.

| Value                  | Effect                                               |
| ---------------------- | ---------------------------------------------------- |
| `https://www.acme.com` | Allow exactly this origin                            |
| One origin per line    | Allow each listed origin                             |
| `*`                    | Allow any origin (use only for fully public widgets) |

<Warning>
  Origin must be an **exact match** — `https://www.acme.com` does **not** allow
  `https://acme.com` or `https://staging.acme.com`. List every host you embed
  on (including local dev URLs like `http://localhost:3000`).
</Warning>

Requests without an `Origin` header (server-to-server calls, `curl`) bypass the check.

***

## Spam protection

Three layers run in order on every submission. Failing any one rejects the request with `400`.

### Honeypot

A hidden decoy field is injected automatically by the SDK. Real users never see it; most spam bots fill every field they find. If it is filled, the submission is dropped. No configuration needed.

### Time-trap

The SDK stamps a render timestamp into the payload. Submissions arriving faster than **Minimum fill time** are rejected as bot traffic.

| Setting                    | Recommended                                     |
| -------------------------- | ----------------------------------------------- |
| **Minimum fill time (ms)** | `1500` for short forms, `3000+` for longer ones |
| **0**                      | Disables the time-trap                          |

### CAPTCHA

When configured, Cargo verifies a CAPTCHA token server-side before running the workflow.

| Provider                 | Where to get keys                                                          |
| ------------------------ | -------------------------------------------------------------------------- |
| **Cloudflare Turnstile** | [Turnstile dashboard](https://dash.cloudflare.com/?to=/:account/turnstile) |
| **hCaptcha**             | [hCaptcha dashboard](https://dashboard.hcaptcha.com/sites)                 |

Configure both fields:

* **Site key** — public, embedded on your page
* **Secret** — server-side only, never sent to the browser

Pass the token from your page into the SDK via `addHiddenFields`:

```html theme={null}
<script>
  Cargo.loadForm("TOOL_UUID", {}, (form) => {
    turnstile.render("#captcha", {
      sitekey: "YOUR_SITE_KEY",
      callback: (token) => {
        form.addHiddenFields({ _cargo_captcha_token: token });
      },
    });
  });
</script>
```

Cargo also has a built-in **per-tool, per-IP rate limit** of 10 submissions per minute. You don't configure it — it's always on.

***

## Appearance

The SDK ships a sensible default stylesheet, but you can theme the form per-workspace so every embed picks up your brand automatically.

| Setting                | Effect                                                                                                               |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Color scheme**       | `Auto` follows the visitor's OS preference, or force `Light` / `Dark`                                                |
| **Primary color**      | Submit button, input focus border and ring, checkbox accent; the button hover shade is derived from it automatically |
| **Primary text color** | Text on top of the primary color (e.g. submit button label)                                                          |
| **Border radius**      | Any CSS length (`6px`, `999px` for fully rounded, …) applied to inputs and the button                                |
| **Font family**        | Any CSS `font-family` value (e.g. `"Inter", system-ui, sans-serif`)                                                  |

Embedders can still override any of these per page via the SDK's `theme` option — workspace defaults are merged with per-call overrides, and explicit overrides win.

In code, `presentation.theme` takes the full theme object — every key is required, and `null` means "use the SDK's bundled default":

```ts theme={null}
presentation: {
  theme: {
    preset: "light",          // "light" | "dark"; null follows the visitor's OS
    primaryColor: "#4f46e5",
    primaryTextColor: null,
    primaryHoverColor: null,
    textColor: null,
    mutedColor: null,
    backgroundColor: null,
    borderColor: null,
    borderFocusColor: null,
    radius: "8px",
    fontFamily: null,
  },
},
```

<Tip>
  Leave a field blank to fall back to the SDK's bundled default. The form
  automatically follows `prefers-color-scheme` unless you force a preset.
</Tip>

***

## Embedding the form

The easiest path is the CDN snippet from the **Embed snippet** section:

```html theme={null}
<div data-cargo-form="TOOL_UUID"></div>
<script>
  window.Cargo = window.Cargo || {};
  Cargo.loadForm = Cargo.loadForm || function () {
    var call = { args: arguments };
    call.promise = new Promise(function (resolve, reject) {
      call.resolve = resolve;
      call.reject = reject;
    });
    (Cargo._q = Cargo._q || []).push(call);
    return call.promise;
  };

  Cargo.loadForm("TOOL_UUID");
</script>
<script src="https://cdn.getcargo.io/forms/v1.js" async></script>
```

That's it — Cargo renders a styled form into the `<div>`, and runs your tool's workflow on submit.

The first few lines are a queueing stub: the CDN script loads with `async`, so it can finish loading before or after your inline code runs. The stub makes `Cargo.loadForm` safe to call immediately — calls are queued and replayed (and their promises resolved) as soon as the bundle loads. Don't remove it, and don't call `Cargo.loadForm` from an inline script without it.

### npm

For SPA or framework projects:

```bash theme={null}
npm install @cargo-ai/form-sdk
```

```ts theme={null}
import { loadForm } from "@cargo-ai/form-sdk";

const form = await loadForm("TOOL_UUID", {
  target: "#cargo-form",
  mode: "sync",
});

form.onSuccess((values, response) => {
  if (response.outcome === "completed") {
    console.log("Workflow output:", response.result.output);
  }
});
```

### Headless mode

Bring your own UI and let the SDK handle validation, anti-spam metadata and submission:

```ts theme={null}
const form = await loadForm("TOOL_UUID", { render: "headless", mode: "async" });

form.setValues({ email: "ada@example.com" });
await form.submit();
```

You're now in full control of the DOM — the SDK just handles the submission plumbing.

***

## SDK reference

### `loadForm(toolUuid, options?, onReady?)`

Loads the deployed schema and returns a `FormInstance`.

| Option           | Default                              | Description                                                                            |
| ---------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
| `render`         | `"render"`                           | `"render"` builds the form DOM; `"headless"` skips DOM rendering                       |
| `mode`           | `"sync"`                             | `"sync"` waits for and returns the run output; `"async"` returns immediately and polls |
| `target`         | `[data-cargo-form="TOOL_UUID"]`      | Element or selector to render into                                                     |
| `autoCaptureUtm` | `true`                               | Capture UTM params + page URL automatically into hidden values                         |
| `submitLabel`    | `"Submit"`                           | Label for the submit button                                                            |
| `classPrefix`    | `"cargo-form"`                       | Prefix for every CSS class emitted by the renderer                                     |
| `injectStyles`   | `true` (render) / `false` (headless) | Inject the bundled default stylesheet once per page                                    |
| `stylesheetUrl`  | —                                    | URL of a custom stylesheet to inject instead of the bundled one                        |
| `theme`          | —                                    | Per-call theme overrides (merged on top of workspace defaults)                         |

### `FormInstance` lifecycle

| Method                    | Purpose                                                                           |
| ------------------------- | --------------------------------------------------------------------------------- |
| `setValues(values)`       | Merge values into the form (visible fields when rendered)                         |
| `addHiddenFields(values)` | Add hidden values sent with the submission (UTMs, lead source, CAPTCHA token, …)  |
| `getValues()`             | Current values (visible + hidden)                                                 |
| `onValidate(handler)`     | Register a validation hook; return `false` to block submission                    |
| `onSubmit(handler)`       | Called right before submit; mutate the returned values to change the payload      |
| `onSuccess(handler)`      | Called after a successful submission; return `false` to suppress default behavior |
| `onError(handler)`        | Called when submission fails                                                      |
| `submit()`                | Programmatically submit (used by headless mode)                                   |

```html theme={null}
<script>
  Cargo.loadForm("TOOL_UUID", { mode: "sync" }, (form) => {
    form.addHiddenFields({ page_url: location.href });

    form.onValidate((values) => {
      return typeof values.email === "string" && values.email.includes("@");
    });

    form.onSuccess(() => {
      location.href = "/thank-you";
      return false;
    });
  });
</script>
```

### Sync vs async submission

| Mode      | Returns                                               | Use when                                                |
| --------- | ----------------------------------------------------- | ------------------------------------------------------- |
| `"sync"`  | Waits up to **60s**, returns the workflow output      | Short workflows (enrichment, scoring) — show the result |
| `"async"` | Returns a `runUuid` immediately; SDK polls for status | Long workflows, or fire-and-forget submissions          |

If a sync run exceeds 60s it falls back to async automatically — `onSuccess` receives a `{ outcome: "pending", runUuid }` response you can keep polling.

***

## Privacy

The SDK is privacy-aware by default:

* Respects [Global Privacy Control](https://globalprivacycontrol.org/) (`Sec-GPC: 1`) and `DNT: 1`. When the visitor has opted out, no anonymous id is set and UTM auto-capture is skipped.
* Form submission is always an explicit user action, so opt-out **never** blocks the submission itself — only passive identity stitching is suppressed.

UTM auto-capture (when enabled) reads `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` and `page_url` from the current URL and includes them as hidden values on submit.

***

## Best practices

<AccordionGroup>
  <Accordion title="Keep allowed origins tight">
    Use `*` only for widgets that genuinely run everywhere. For anything else,
    list each host explicitly — it stops other sites from embedding your form
    and burning your credits.
  </Accordion>

  <Accordion title="Pair honeypot with CAPTCHA on high-value forms">
    Honeypot + time-trap catch nearly all unsophisticated bots for free. Add
    Turnstile or hCaptcha when the form triggers credit-heavy work (AI nodes,
    enrichment) or feeds downstream systems like a CRM.
  </Accordion>

  <Accordion title="Use async mode for long workflows">
    Browsers won't wait long. If your tool routinely takes more than a few
    seconds (AI calls, multi-step enrichment), switch to `mode: "async"` and
    show a "we'll be in touch" screen instead of a spinner.
  </Accordion>

  <Accordion title="Capture context with hidden fields">
    Beyond UTMs, pass `page_url`, `referrer`, `plan_tier`, or anything else
    your workflow can branch on via `form.addHiddenFields({ ... })`. They're
    sent as regular workflow inputs — define matching fields on the tool's
    Input node.
  </Accordion>

  <Accordion title="Test the embed on your real site">
    Origin / CORS issues only surface in a real browser on a real domain.
    Always test the snippet on the page you'll actually embed on, not just
    `localhost`.
  </Accordion>
</AccordionGroup>


# Triggering a tool
Source: https://docs.getcargo.ai/tools/triggering

Run a tool from the CLI, on a schedule declared in code, from plays/agents/MCP, over the API, or from the UI

Once a tool is deployed (`cargo-ai project deploy`), you can run it many ways. The code-first paths — the CLI and cron triggers declared in `defineTool` — are covered first; the UI Trigger tab is the same thing with a mouse.

## From the CLI

The CLI is the fastest way to run a deployed tool. Find the tool's `workflowUuid`, then create a run.

```bash theme={null}
cargo-ai orchestration tool list                 # → workflowUuid
```

### Single run

```bash theme={null}
cargo-ai orchestration run create \
  --workflow-uuid <uuid> \
  --data '{"company_domain":"acme.com","contact_email":"john@acme.com"}' \
  --wait-until-finished
```

<Note>
  `run create` works with **tool** workflows only. For plays, use `batch create`
  instead — see [Triggering a play](/plays/triggering).
</Note>

### Bulk run

Run the tool across many records with a single batch:

```bash theme={null}
cargo-ai orchestration batch create \
  --workflow-uuid <uuid> \
  --data '{"kind":"records","records":[
    {"company_domain":"acme.com","contact_email":"john@acme.com"},
    {"company_domain":"globex.io","contact_email":"jane@globex.io"}
  ]}'

cargo-ai orchestration batch get <batch-uuid>     # poll for completion
```

<Tip>
  Ramp batch sizes gradually — 1 record, then 50, then the full set — so
  connector rate limits surface before they affect thousands of rows.
</Tip>

## On a schedule (cron triggers)

Declare recurring runs directly on the tool. Triggers live in code, so they're versioned and deployed with everything else:

```ts tools/enrich.ts theme={null}
export const enrich = defineTool("enrich", {
  workflow: enrichFlow,
  triggers: [
    { cron: "0 9 * * 1", name: "Weekly enrichment" },
    { cron: "0 */6 * * *", name: "Every 6 hours", data: { source: "scheduled" } },
  ],
});
```

Cron is the only trigger kind tools support. `data` is passed as the run input each time the schedule fires. `cargo-ai project deploy` reconciles the trigger list.

## Inside a play, agent, or MCP server

Tools are meant to be composed. Reference the tool handle in code and the platform wires the rest:

```ts theme={null}
// In a workflow (play or another tool) — call it via `uses`
const flow = defineWorkflow("onboard", { input, output, uses: { enrich } },
  ({ input, uses }) => uses.enrich({ email: input.email }),
);

// In an agent — expose it as a callable tool
export const sdr = defineAgent("sdr", { uses: [enrich], /* … */ });

// Over MCP — publish it to external AI clients
export const server = defineMcpServer("gtm", { uses: [enrich] });
```

See [Plays](/plays/overview), [Agents](/agents/overview), and [MCP servers](/mcp-servers/overview).

## Over the API

Execute a tool synchronously via REST. If execution exceeds 5 minutes it times out.

```bash theme={null}
curl -X POST "https://api.getcargo.io/v1/tools/{tool_id}/execute?token={your_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "company_domain": "acme.com",
    "contact_email": "john@acme.com"
  }'
```

```json theme={null}
{
  "status": "success",
  "createdAt": "2024-01-15T10:30:00Z",
  "finishedAt": "2024-01-15T10:30:02Z",
  "input": { "company_domain": "acme.com", "contact_email": "john@acme.com" },
  "output": { "company_name": "Acme Corporation", "employee_count": 500, "industry": "Technology" }
}
```

### Batch execution

For many records or long-running operations, use the batch API. Creating a
batch returns `202 Accepted` with a `Location` header pointing at the batch.
Poll that URL, or `batch get` with the returned uuid, until the batch reaches
a terminal status.

```bash theme={null}
curl -X POST "https://api.getcargo.io/v1/tools/{tool_id}/batches?token={your_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/cargo-callback",
    "webhookSecret": "your-secret",
    "data": [
      {"company_domain": "acme.com", "contact_email": "john@acme.com"},
      {"company_domain": "globex.io", "contact_email": "jane@globex.io"}
    ]
  }'
```

`webhookUrl` is optional. When set, results are POSTed there on completion. `webhookSecret` is also optional — when provided, Cargo signs every delivery with an HMAC-SHA256 signature in the `X-Cargo-Signature` header (`sha256=<hex>`). Verify it before trusting a delivery:

```ts theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

function isValidSignature(rawBody: string, secret: string, header: string) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}
```

Poll for results with the batch UUID, and cancel if needed:

```bash theme={null}
curl "https://api.getcargo.io/v1/tools/{tool_id}/batches/{batch_uuid}?token={your_token}"
curl -X POST "https://api.getcargo.io/v1/tools/{tool_id}/batches/{batch_uuid}/cancel?token={your_token}"
```

## Public form

Expose the tool as a hosted, embeddable web form that runs its workflow on submit. See [Public form](/tools/public-form).

## From the UI

The **Trigger** tab mirrors the CLI: **Single** runs one record, **Bulk** uploads a CSV whose headers map to the tool's input fields. Good for ad-hoc testing without a terminal.

<img alt="Triggering a tool" />

```csv theme={null}
company_domain,contact_email
acme.com,john@acme.com
globex.io,jane@globex.io
```

## Choosing a method

| Method           | Best for                                 | Automation level |
| ---------------- | ---------------------------------------- | ---------------- |
| **CLI**          | Scripted, ad-hoc, and CI-driven runs     | Fully automated  |
| **Cron trigger** | Recurring runs declared in code          | Fully automated  |
| **Plays**        | Event-driven, multi-step automation      | Fully automated  |
| **Agents**       | Context-aware, AI-driven invocation      | AI-driven        |
| **MCP server**   | External AI system integration           | AI-driven        |
| **API**          | Custom applications, programmatic access | Fully automated  |
| **Trigger tab**  | Testing and one-off runs                 | Manual           |


# Using UI
Source: https://docs.getcargo.ai/tools/using-ui

Learn what tools are, and how to build your first one.

<iframe title="Build a tool in Cargo" />

## What are tools?

Tools are modular, reusable automation workflows that you can build once and deploy anywhere. They encapsulate repeatable actions—like finding stakeholders, extracting revenue data, or qualifying leads—so you can scale your GTM workflows without rebuilding logic from scratch.

Once published, tools can be:

* **Triggered in plays** to run as part of automated workflows
* **Leveraged by agents** to accomplish complex tasks
* **Deployed to MCP servers** for external integrations
* **Called via API** from your own applications

> The more you invest in your Cargo tools, the more efficient and robust your GTM systems become.

***

## Use cases

Here are some of the most popular ways Cargo customers use tools:

* **Lead qualification:** Automate the process of qualifying leads based on custom criteria and real-time data.
* **Custom data enrichment:** Pull key company metrics (like 2024 revenue) from multiple sources automatically.
* **Stakeholder discovery:** Find and surface the right contacts at target accounts.
* **Outreach automation:** Send emails or trigger other communications as part of a larger workflow.
* **CRM hygiene:** Detect and fix data quality issues like invalid emails or duplicate records.

***

## Step-by-step: Build your first tool

Follow these steps to create a tool that finds stakeholders at a company based on a prompt.

### Step 1: Create a new tool

1. Navigate to **Tools** in your Cargo workspace sidebar
2. Click **+ New Tool** in the top right corner
3. Give your tool a descriptive name (e.g., "Find stakeholders from a prompt")
4. You'll be taken to the tool editor canvas

<img alt="The tool editor canvas" />

### Step 2: Define your inputs

Every tool needs input data to work with. Click on the **Start** node to configure your inputs:

| Property          | Description                                                             |
| ----------------- | ----------------------------------------------------------------------- |
| **Field name**    | The identifier for this input (e.g., `company_domain`, `search_prompt`) |
| **Type**          | Data type: `string`, `number`, `boolean`, `array`, or `object`          |
| **Required**      | Whether this field must be provided for the tool to execute             |
| **Description**   | Help text explaining what this field is for                             |
| **Default value** | Fallback value if none is provided (optional)                           |

<Tip>
  Use `snake_case` for field names (e.g., `company_name` instead of
  `companyName`) for consistency across your workspace.
</Tip>

### Step 3: Add nodes to build your workflow

Click the **+** button to add nodes to your workflow. For this example, we'll build a stakeholder finder:

1. Add an **Instruct** node to convert natural language to structured criteria
2. Add an **Enrich company** node to gather company data
3. Add a **Branch** node to check if the enrichment succeeded
4. Add a **Search leads** node to find relevant contacts
5. Add a **Script** node to format the output

<img alt="Connecting nodes in the tool editor" />

### Step 4: Connect your nodes

To connect nodes, click on the output handle of one node and drag it to the input handle of the next:

* Connections define how data flows through your tool
* Branch nodes have multiple outputs (YES/NO) for conditional logic
* A node's output can connect to multiple downstream nodes

### Step 5: Map data between nodes

Use expressions to pass data from one node to another. In any input field, reference outputs from previous nodes:

```
{{nodes.start.company_domain}}
{{nodes.enrich_company.employee_count}}
{{nodes.instruct.result}}
```

<Note>
  Check the [expressions cheatsheet](/reference/expressions-cheatsheet) for
  all available syntax and functions.
</Note>

### Step 6: Configure your output

Define what your tool returns by configuring the **End** node:

1. Click on the **End** node
2. Map the fields you want to return (e.g., stakeholder names, titles, LinkedIn URLs)
3. These outputs can be used by plays, agents, or external systems calling your tool

### Step 7: Test your tool

Before publishing, validate your tool works correctly:

1. Click the **Test** button in the bottom toolbar
2. Enter sample input data
3. Click **Run** to execute the tool
4. Inspect each node's output in the execution view
5. Fix any errors that appear

<Warning>
  Test mode uses real integrations and may consume credits or modify external
  systems. Use test data when possible.
</Warning>

### Step 8: Publish your tool

Once everything works, publish your tool to make it available:

<img alt="Publishing a tool with version control" />

1. Click **Publish** in the top right corner
2. Choose a version type (Major, Minor, or Patch)
3. Add a description of your changes
4. Click **Publish** to deploy

<Note>
  Publishing creates a new version. Active plays and agents continue using the
  version they were configured with until you explicitly update them.
</Note>

***

## Managing versions

Tools support full version control so you can iterate safely:

<img alt="Version history and draft management" />

* **Drafts:** Changes are auto-saved as drafts until you publish
* **Version history:** Access previous versions from the dropdown menu
* **Rollback:** Revert to any previous version if needed

***

## Best practices

<AccordionGroup>
  <Accordion title="Name everything descriptively">
    Rename nodes from defaults like "Branch 1" to something meaningful like
    "Check if enterprise tier". Your future self will thank you.
  </Accordion>

  <Accordion title="Handle errors explicitly">
    Don't assume every node will succeed. Use Branch nodes to check for errors
    and handle them gracefully—log failures, send notifications, or trigger
    fallback logic.
  </Accordion>

  <Accordion title="Keep tools focused">
    Build tools that do one thing well rather than trying to handle every edge
    case. You can always chain tools together in plays or let agents orchestrate
    multiple tools.
  </Accordion>

  <Accordion title="Document your inputs">
    Add descriptions to every input field. When someone else (or future you)
    uses this tool, they'll know exactly what data to provide.
  </Accordion>

  <Accordion title="Test with edge cases">
    Don't just test the happy path. What happens with missing data? Invalid
    formats? API rate limits? Test these scenarios before publishing.
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup>
  <Card title="Explore actions" icon="bolt" href="/workflows/overview#the-action-catalog">
    Browse the 120+ actions in the editor's node palette — and how to list them
    from the CLI.
  </Card>

  <Card title="Trigger your tool" icon="rocket" href="/tools/triggering">
    Discover the different ways to trigger your tools.
  </Card>

  <Card title="Monitor performance" icon="chart-line" href="/tools/monitoring">
    Track executions, debug failures, and optimize your tools.
  </Card>

  <Card title="Embed in CRM" icon="window-restore" href="/tools/embed-in-crm">
    Trigger tools directly from Salesforce with custom buttons.
  </Card>
</CardGroup>


# Workers & apps
Source: https://docs.getcargo.ai/workers-and-apps/overview

Deploy hosted edge workers and Vite single-page apps as part of your workspace with defineWorker and defineApp.

Cargo hosts two kinds of custom code alongside your resources: **workers** (serverless edge HTTP handlers) and **apps** (Vite single-page apps served on `*.cargo.app`). `defineWorker` and `defineApp` deploy a **source bundle directory** that Cargo Hosting builds on deploy.

## Define a worker

```ts workers/webhook.ts theme={null}
import { defineWorker, secret } from "@cargo-ai/cdk";

// bundle root needs: manifest.json + package.json + package-lock.json,
// plus a TS entry `src/index.ts` (or a pre-built `index.js`)
export const webhook = defineWorker("webhook", {
  path: new URL("./webhook", import.meta.url).pathname,
  // env vars baked into the build; secret("NAME") reads the value at deploy
  // time and stores it as a secret env var
  env: {
    CARGO_API_TOKEN: secret("CARGO_API_TOKEN"),
    LOG_LEVEL: "info",
  },
  // optional: call the worker on a schedule
  triggers: [
    {
      name: "Sync",
      cron: "@every 1h",
      path: "/cron/sync",
      data: { mode: "incremental" },
      headers: { authorization: "Bearer <something-strong>" },
    },
  ],
});
```

## Define an app

```ts apps/dashboard.ts theme={null}
import { defineApp } from "@cargo-ai/cdk";

// bundle root needs: index.html + package.json + package-lock.json (a Vite app)
export const dashboard = defineApp("dashboard", {
  path: new URL("./dashboard", import.meta.url).pathname,
});
```

Cargo validates the required bundle files exist at define time, so a missing file fails in `plan`.

## Environment variables

A worker reads its variables from `c.env`, an app from `import.meta.env.VITE_*`. Both are baked in when the deployment is built, so a change needs a redeploy.

Set them on the resource — through `env` above, or its Environment tab in the Cargo app — or once for the whole workspace under **Settings → Environment**, which every worker and app inherits without declaring anything. A key set on the resource overrides the workspace value; an app only inherits non-secret `VITE_` keys, since its bundle is served to the browser. See [Secrets & environments](/reference/secrets-and-environments#workspace-environment-variables).

Because the inheritance is automatic, a resource's `env` takes `env()` or `secret()` and *not* `workspaceEnv()` — declaring a pointer here would only restate a variable the worker or app already receives. Leave a workspace variable out of `env` entirely.

<Note>
  `defineWorker`/`defineApp` are the deployable **resource** (the hosted slot).
  Author the worker's runtime code in TypeScript with `createWorker` from
  `@cargo-ai/worker-sdk` at `src/index.ts` — bundles are uploaded as source and
  built server-side: the hosting build runs `npm ci` then esbuilds the worker
  entrypoint (esbuild transpiles TypeScript natively) or `vite build` for apps.
  A pre-built `index.js` at the bundle root is still accepted for backwards
  compatibility. Bundle sub-directories have their own `package.json`, so the
  loader treats them as content to upload, not resource files to import.
</Note>

## Cron triggers

A worker can be called on a schedule: each trigger describes the full request Cargo fires — cron (or Temporal's `@every` shorthand), path, method (default `POST`), a JSON body, and headers. Set an `authorization` header and guard the route with standard Hono middleware (`bearerAuth`/`basicAuth`); ticks only fire once the worker has a promoted deployment.

Triggers can be set from the worker's page in the Cargo app, via `defineWorker` (above), or with the CLI/API:

```bash theme={null}
cargo-ai hosting worker update --uuid <workerUuid> \
  --triggers '[{"type":"cron","name":"Sync","cron":"@every 1h","path":"/cron/sync","method":"POST"}]'
```

## Calling the Cargo API

Create a workspace API token and add it to the worker as a `CARGO_API_TOKEN` secret environment variable — the Cargo API host is allowed without an `outboundAllowlist` entry. `createCargoApi(env)` from `@cargo-ai/worker-sdk` returns the fully-typed `@cargo-ai/api` client:

```ts theme={null}
import { createCargoApi } from "@cargo-ai/worker-sdk";

app.get("/workers", async (c) => {
  const api = createCargoApi(c.env);
  const { workers } = await api.hosting.worker.list();
  return c.json(workers);
});
```

## Custom integrations

A worker that serves the Custom Integration HTTP contract (`createCustomIntegration` from `@cargo-ai/worker-sdk`) can be registered in the connector catalog declaratively:

```ts theme={null}
import { defineCustomIntegration } from "@cargo-ai/cdk";

export const integration = defineCustomIntegration("my-integration", {
  worker: webhook,
});
```

## Scaffolding and deploying standalone

You can also scaffold and ship bundles directly with the CLI:

```bash theme={null}
cargo-ai hosting app init my-app          # scaffold a Vite app
cargo-ai hosting worker init my-worker    # scaffold an edge worker
cargo-ai hosting deployment create --app-uuid <uuid> --source .
cargo-ai hosting deployment promote --uuid <deployment-uuid>
```

Slugs are kebab-case and must start with a letter (`my-worker`).


# Workflows
Source: https://docs.getcargo.ai/workflows/overview

defineWorkflow — the TypeScript DSL that backs tools and plays. Author logic in code that compiles to the same nodes as the visual editor.

A **workflow** is the logic that a [tool](/tools/overview) runs or a [play](/plays/overview) executes per row. You author it in TypeScript with `defineWorkflow` from `@cargo-ai/cdk` (re-exported from `@cargo-ai/workflow-sdk`).

Workflows authored in code and workflows drawn on the canvas compile to the **same** artifact and run identically — the code DSL is just a different authoring surface.

## Define a workflow

```ts theme={null}
import { defineWorkflow } from "@cargo-ai/cdk";
import { z } from "zod";
import { enricher } from "../agents/enricher";

export const enrichFlow = defineWorkflow(
  "enrich-contact",
  {
    input: z.object({ email: z.string() }),
    output: z.object({ company: z.string(), enriched: z.boolean() }),
    uses: { enricher }, // tools/agents this workflow calls, by handle
  },
  ({ input, uses, ai }) => {
    // An agent call resolves to `{ answer, evaluation? }` — read `.answer`.
    const company = uses.enricher({
      prompt: `Which company owns the email domain of ${input.email}?`,
    }).answer;
    return { company, enriched: true };
  },
);
```

* `input` / `output` are Zod schemas — they become the workflow's form fields and end variables.
* `uses` declares the tools, agents, and connectors this workflow calls (see [below](#reference-tools-agents-and-connectors)).
* The **body is parsed, not executed.** The SDK reads the function's source and lowers it to workflow nodes; it never runs at build time. That's why the body can't be `async` and why only a subset of JavaScript is supported (see below) — anything that must run at runtime goes in a `js()` block.

## Reference tools, agents, and connectors

Everything a workflow calls that isn't a native action — a **tool**, an **agent**, or a **connector** — is declared once in the header's `uses` map and called by key in the body. Keeping the reference in the header (not inline in the body) lets the deploy order the dependency and inject the real uuid.

```ts theme={null}
import { connectorRef } from "@cargo-ai/workflow-sdk";

defineWorkflow(
  "qualify-lead",
  {
    input: z.object({ email: z.string() }),
    output: z.unknown(),
    uses: {
      enrich: enrichTool, //     a defineTool handle
      sdr: sdrAgent, //          a defineAgent handle
      hubspot: hubspotConnector, // a defineConnector handle
      hunter: connectorRef("6f0c…", "hunter"), // …or a connector by uuid + slug
    },
  },
  ({ input, uses }) => {
    const verified = uses.enrich({ email: input.email }); // tool → call by key
    const contact = uses.hubspot.upsertContact({ email: input.email }); // connector → call an action
    return contact;
  },
);
```

* **Tools and agents** are called directly — `uses.<key>(input)`.
* **Connectors** expose their actions — `uses.<key>.<action>(input)`. Action names and their input/output are typed from the integration's schema (run `cargo-ai project types`). The type comes from the integration **slug**, not the uuid — so the connector's uuid can be a handle for a resource that doesn't exist yet.
* Pass a `defineTool` / `defineAgent` / `defineConnector` handle directly, or use `toolRef` / `agentRef` / `connectorRef(uuid, slug)` for a resource referenced by literal uuid.

## What you can express in code

| Capability                      | In code                                                                                                                                       |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Call a tool / agent / connector | `uses.<key>(input)` (tool / agent) or `uses.<key>.<action>(input)` (connector) — [declared in `uses`](#reference-tools-agents-and-connectors) |
| Storage actions                 | `model.search / upsert / update / insert / remove / record / ask / customColumn`                                                              |
| Native helpers                  | `python(input)`, `scoring(input)`, `allocate(input)`, `delay(input)`, `fileSearch(input)`, `sendEmail(input)`, `waitEmailEvent(input)`        |
| Branch                          | `if (cond) { … } else { … }`                                                                                                                  |
| Switch                          | `if … else if … else …`                                                                                                                       |
| Loop over a list                | `for (const x of items) { … }`                                                                                                                |
| Inline AI value                 | `ai(\`prompt \$\`)\`                                                                                                                          |
| Custom JavaScript               | `js(({ nodes }) => …)`                                                                                                                        |
| Human approval                  | `humanReview(config, { approved, declined })`                                                                                                 |
| Memory (KV)                     | `memory.get / set / getOrSet / remove / increment / decrement`                                                                                |
| Traffic split / balance         | `split(30, { left, right })`, `balance([...])`                                                                                                |

Supported statements: `const` / `let` (single identifier), `if` / `else if` / `else`, `for…of`, and `return`. Not supported: `async`/`await`, `try/catch`, `throw`, closures, nested function declarations, and destructuring assignments.

## Built-in actions

### `ai()` — inline AI value

Ask an LLM for a single value anywhere an expression fits:

```ts theme={null}
const summary = ai(`Summarize what ${input.domain} sells in one sentence.`);
```

### `js()` — runtime JavaScript

Escape hatch for logic the parser can't lower — the function you pass **does** run at runtime, as a script node, with access to upstream node outputs:

```ts theme={null}
const normalized = js(({ nodes }) => {
  const raw = nodes.enricher.answer;
  return raw.trim().toLowerCase();
});
```

Use `js()` for transformations, parsing, and computation; keep orchestration (branches, loops, action calls) in the DSL where it compiles to inspectable nodes. `python(...)` is the same idea in Python.

Inside the sandbox, `require()` is limited to `axios`, `cheerio`, `crypto-js`, `date-fns`, `jsonschema`, `lodash`, `url`, `uuid`, and `zod`. Anything else throws, including `knex` — call HTTP APIs with `axios`.

### `sendEmail()` — send from a Cargo mailbox

Deliver one message from a mailbox the workspace owns. Orchestration paces the send against that mailbox's daily allowance. See [Mailboxes](/mailboxes/overview) and [Sending](/mailboxes/sending).

```ts theme={null}
const sent = sendEmail({
  mailboxUuid: "11111111-1111-1111-1111-111111111111",
  to: input.email,
  subject: `Quick note, ${input.firstName}`,
  bodyHtml: `<p>Hi ${input.firstName},</p>`,
});
```

### `waitEmailEvent()` — pause until the thread moves

After `sendEmail`, wait until the conversation is replied to, viewed, interacted with, or unsubscribed. Matching is **per thread**: an event on any send in that conversation completes the wait. If `timeoutHours` elapses first, the node **fails** the run — same as a human-review timeout.

```ts theme={null}
const sent = sendEmail({
  mailboxUuid: "11111111-1111-1111-1111-111111111111",
  to: input.email,
  subject: `Quick note, ${input.firstName}`,
  bodyHtml: `<p>Hi ${input.firstName},</p>`,
});

waitEmailEvent({
  messageUuid: sent.messageUuid,
  kind: "replied",
  timeoutHours: 72,
});
```

| Field          | Required | Meaning                                                                                           |
| -------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `messageUuid`  | yes      | Usually `sent.messageUuid`. The wait loads that message and keys off its `threadUuid`.            |
| `kind`         | yes      | `replied`, `opened` (shown as When viewed), `unsubscribed`, or `interacted` (view, click, reply). |
| `timeoutHours` | no       | Hours to wait before failing. Defaults to 72, capped at 720 (30 days).                            |

If the activity already happened, the node completes immediately — it does not wait.

### `humanReview()` — human-in-the-loop gate

Posts a Slack message with Approve / Decline buttons and **blocks the run** until a reviewer clicks one (or the timeout fires — timeouts auto-decline):

```ts theme={null}
humanReview(
  {
    connectorUuid: slack.uuid, // the Slack connector to post through
    channelId: "C0123456789",
    title: "Approve outreach?",
    content: `Sending sequence to *${input.email}*`,
    timeoutMilliseconds: 86_400_000, // default: 24 hours
    enableEditButton: true, // default: true
  },
  {
    approved: () =>
      uses.lemlist.createLead({ campaignId: "cam_123", email: input.email }),
    declined: () =>
      memory.increment({
        key: "declined",
        expiresIn: { value: 30, unit: "day" },
      }),
  },
);
```

### `memory.*` — key-value state

Persist state across runs without a model. Each call is one node and returns `{ result }`:

```ts theme={null}
const seen = memory.get<number>({ key: input.email });
if (seen.result === null) {
  memory.set({
    key: input.email,
    value: 1,
    expiresIn: { value: 7, unit: "day" },
  });
}
```

* `scope: "workflow"` (default) is private to this workflow; `"workspace"` is shared across all workflows.
* `set`, `getOrSet`, `increment`, and `decrement` require `expiresIn` (`{ value, unit }` with `second` / `minute` / `hour` / `day`).
* `increment` / `decrement` are atomic counters — the safe way to rate-limit or cap sends.

### `split()` and `balance()` — traffic shaping

```ts theme={null}
// A/B: ~30% of records run left, the rest right
split(30, {
  left: () =>
    uses.lemlist.createLead({ campaignId: "cam_A", email: input.email }),
  right: () =>
    uses.lemlist.createLead({ campaignId: "cam_B", email: input.email }),
});

// Round-robin: each record runs exactly ONE route; returns the first non-null output
const result = balance([
  () => uses.hunter.findEmail({ domain: input.domain }),
  () => uses.dropcontact.findEmail({ website: input.domain }),
]);
```

Route bodies must be inline zero-argument arrows.

## The action catalog

Cargo ships **120+ actions** across enrichment, CRM, AI, communication, and logic. Three ways to browse what's callable:

```bash theme={null}
cargo-ai connection integration list             # every integration and its slug
cargo-ai connection integration get hubspot      # one integration's actions + config schemas
cargo-ai project types                               # generate the typed uses.<key>.<action> registry
```

* **In code**, `cargo-ai project types` writes the registry into `.cargo-ai/`, so a connector declared in `uses` (`uses.<key>.<action>`) autocompletes real action slugs and config shapes in your editor.
* **In the UI**, the same catalog is the node palette in the [tool editor](/tools/using-ui) — searchable by category, with per-field documentation inline.
* **Per integration**, each page in the [Integrations tab](/integration/overview) documents its actions, parameters, and credit costs.

## Code covers a subset of the canvas

The code DSL is designed for linear and branching tool/play logic. It does **not** yet mirror the entire visual node palette. These are **canvas-only** today — build them in the [tool editor](/tools/using-ui) if you need them:

* **Filter**, **Delay**, and **Variables** nodes
* **Model** actions — search, insert, update, upsert, remove, custom column
* **File search** and **Model ask** standalone AI nodes
* **Allocate** (lead routing)

<Note>
  Because both paths compile to the same node format, you can start a workflow
  in code and finish complex, canvas-only parts in the UI, or vice versa. But
  the project never reads UI edits back into your files — once you finish a workflow
  in the UI, re-deploying a changed code definition overwrites the canvas work.
  See [Code and UI round-trips](/deploy/state-and-drift#code-and-ui-round-trips)
  before mixing the two on one resource.
</Note>

## Retry and failure options

Every connector, tool, and agent call accepts a second options argument:

```ts theme={null}
uses.hunter.findEmail(
  { domain },
  {
    retry: { maximumAttempts: 3, initialInterval: 1000, backoffCoefficient: 2 },
    continueOnFailure: true,
  },
);
```

## Deploying workflow changes

A workflow is deployed as part of the tool or play that owns it (`cargo-ai project deploy`). You can also push a Workflow SDK module to an existing workflow directly:

```bash theme={null}
cargo-ai orchestration release deploy-draft --file ./enrichFlow.ts
```