> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/rudderstack.md).

# RudderStack

Connect to RudderStack to send customer event data and manage the pipeline: record track events, update user profiles with identify calls, import events in bulk, create a new event source and read back its write key, and list the destinations a workspace sends data to.

## Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector                  | Authentication   |
| -------------------------- | ---------------- |
| RudderStack (Write Key)    | Source Write Key |
| RudderStack (Access Token) | Access Token     |

### RudderStack (Write Key)

Send events to a RudderStack source with its write key and your workspace's data plane URL. This is the connection the Send Track Event, Identify User and Batch Import Events actions use. It cannot manage the workspace: creating sources and listing destinations needs a RudderStack (Access Token) connection instead.

#### Set up in RudderStack

1. Prepare the RudderStack account or service that the workflow will access. Grant access to the required resources and operations.
2. **Source Write Key:** The write key of the RudderStack source you want to send events to. Find it in the RudderStack dashboard: open the source, then its Settings tab. Paste only the key. RudderStack authenticates it as the HTTP Basic username with an empty password, which this integration handles for you, so there is no password to enter anywhere.
3. **Data Plane URL:** The URL RudderStack shows at the top of your Connections page, for example <https://yourco.dataplane.rudderstack.com>. Enter the https origin only, with no path. This is where events are sent, and it is different from the RudderStack API host used for managing the workspace.

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **RudderStack (Write Key)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field    | Required | What to enter                                                                                                                                                                                                                                                                                                                            |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Source Write Key | Yes      | The write key of the RudderStack source you want to send events to. Find it in the RudderStack dashboard: open the source, then its Settings tab. Paste only the key. RudderStack authenticates it as the HTTP Basic username with an empty password, which this integration handles for you, so there is no password to enter anywhere. |
| Data Plane URL   | Yes      | The URL RudderStack shows at the top of your Connections page, for example <https://yourco.dataplane.rudderstack.com>. Enter the https origin only, with no path. This is where events are sent, and it is different from the RudderStack API host used for managing the workspace.                                                      |

### RudderStack (Access Token)

Manage a RudderStack workspace with a Service Access Token or Personal Access Token. This is the connection the Create Source and List Destinations actions use. It cannot send events: that needs a RudderStack (Write Key) connection, because a write key and an access token are not interchangeable and the two planes share no host.

#### Set up in RudderStack

1. Prepare the RudderStack account or service that the workflow will access. Grant access to the required resources and operations.
2. **Access Token:** A RudderStack Service Access Token or Personal Access Token. Service tokens exist only on RudderStack's Enterprise plan: Settings, Organization, Service Access Tokens, then the Workspace tab; only Org Admins can create one. On other plans use a Read-Write personal token: Settings, Your Profile, Personal Access Tokens. A personal token is limited to the role of the user who created it, so a read-only user's read-write token stays read-only and cannot create sources.
3. **Region:** The RudderStack region hosting your workspace: 'us' for app.rudderstack.com or 'eu' for eu.dashboard.rudderstack.com. An EU workspace queried against the US host returns 404 for resources that do exist.

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **RudderStack (Access Token)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required                 | What to enter                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Access Token  | Yes                      | A RudderStack Service Access Token or Personal Access Token. Service tokens exist only on RudderStack's Enterprise plan: Settings, Organization, Service Access Tokens, then the Workspace tab; only Org Admins can create one. On other plans use a Read-Write personal token: Settings, Your Profile, Personal Access Tokens. A personal token is limited to the role of the user who created it, so a read-only user's read-write token stays read-only and cannot create sources. |
| Region        | Optional / as applicable | The RudderStack region hosting your workspace: 'us' for app.rudderstack.com or 'eu' for eu.dashboard.rudderstack.com. An EU workspace queried against the US host returns 404 for resources that do exist.                                                                                                                                                                                                                                                                            |

### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

## Use an action

1. Add the required **RudderStack** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

## Actions

### Send Track Event

Record a single user action in RudderStack, such as 'Order Completed' or 'Signup Started'.

#### Inputs

| Field                      | Type     | Required | Description                                                                                                                                    |
| -------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Event Name                 | string   | Yes      | The name of the action the user took. Use the same name every time so RudderStack can group these events.                                      |
| User ID                    | string   | No       | Your own unique id for the signed-in user. Leave blank for a visitor you cannot identify yet and fill in Anonymous ID instead.                 |
| Anonymous ID               | string   | No       | A stable id for a visitor who has not signed in yet, such as a browser or device id.                                                           |
| Event Properties (JSON)    | textarea | No       | Extra detail about this event as a JSON object, for example the order total or the plan name.                                                  |
| Event Time                 | datetime | No       | When the action actually happened. Leave blank and RudderStack stamps the time it received the event.                                          |
| Context (JSON)             | textarea | No       | Advanced. Environment detail about the event as a JSON object, such as app, page or device information.                                        |
| Destination Routing (JSON) | textarea | No       | Advanced. Choose which connected destinations receive this event, as a JSON object.                                                            |
| User Traits (JSON)         | textarea | No       | Advanced. Traits about the person to attach to this event, as a JSON object. Use Identify User instead when you only want to update a profile. |
| Message ID                 | string   | No       | Advanced. Your own unique id for this event. Re-sending the same id within 7 days will not create a duplicate on RudderStack Cloud.            |

#### Outputs

| Field      | Type    | Description                                                                                                                          |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Accepted   | boolean | True when RudderStack accepted the event. Acceptance is not delivery: routing to destinations happens later and is not visible here. |
| Message ID | string  | The unique id sent with this event. Reuse it to re-send the same event without creating a duplicate.                                 |
| Event Name | string  | The event name that was recorded.                                                                                                    |

### Identify User

Create or update a person's profile in RudderStack with traits such as email, name and plan.

#### Inputs

| Field                      | Type     | Required | Description                                                                                                                                            |
| -------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| User ID                    | string   | No       | Your own unique id for this person. Use this whenever you know who they are.                                                                           |
| Anonymous ID               | string   | No       | A stable id for a visitor who has not signed in yet, such as a browser or device id.                                                                   |
| Email                      | string   | No       | The person's email address. RudderStack stores it as the reserved 'email' trait, which most destinations match people on.                              |
| Full Name                  | string   | No       | The person's full name. RudderStack stores it as the reserved 'name' trait.                                                                            |
| Traits (JSON)              | textarea | No       | Everything else you know about this person, as a JSON object. RudderStack reserves keys like firstName, lastName, phone, company, title and createdAt. |
| Event Time                 | datetime | No       | When these traits were true. Leave blank and RudderStack stamps the time it received the event.                                                        |
| Context (JSON)             | textarea | No       | Advanced. Environment detail as a JSON object, such as app or device information.                                                                      |
| Destination Routing (JSON) | textarea | No       | Advanced. Choose which connected destinations receive this profile update, as a JSON object.                                                           |
| Message ID                 | string   | No       | Advanced. Your own unique id for this update. Re-sending the same id within 7 days will not create a duplicate on RudderStack Cloud.                   |

#### Outputs

| Field         | Type    | Description                                                                                                                                   |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Accepted      | boolean | True when RudderStack accepted the profile update. Acceptance is not delivery: routing to destinations happens later and is not visible here. |
| Message ID    | string  | The unique id sent with this update. Reuse it to re-send without creating a duplicate.                                                        |
| Identified As | string  | The id this profile was filed under, either the User ID or the Anonymous ID.                                                                  |

### Batch Import Events

Send many RudderStack events in one call, mixing track, identify, page, screen and group events.

#### Inputs

| Field                      | Type     | Required | Description                                                                                                                                                                  |
| -------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Events (JSON Array)        | textarea | Yes      | A JSON list of events. Each event needs a "type" (track, identify, page, screen or group), an id for the person, and whatever that event type needs.                         |
| Shared Context (JSON)      | textarea | No       | Advanced. Context applied to every event in the batch that does not set its own, as a JSON object.                                                                           |
| Destination Routing (JSON) | textarea | No       | Advanced. Choose which connected destinations receive this batch, as a JSON object.                                                                                          |
| Message ID Prefix          | string   | No       | Advanced. Your own prefix for the ids of events that don't bring one. Re-sending a batch with the same prefix within 7 days will not create duplicates on RudderStack Cloud. |

#### Outputs

| Field                | Type    | Description                                                                                                                          |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Accepted             | boolean | True when RudderStack accepted the batch. Acceptance is not delivery: routing to destinations happens later and is not visible here. |
| Events Sent          | integer | How many events were in the batch.                                                                                                   |
| Payload Size (Bytes) | integer | The size of the request that was sent, so you can see how close the batch is to RudderStack's 4 MB limit.                            |
| Message ID Prefix    | string  | The id prefix used for events that did not bring their own. Elements were sent as prefix-0, prefix-1 and so on.                      |

### Create Source

Create a new event source in your RudderStack workspace and get back its write key.

#### Inputs

| Field                | Type            | Required | Description                                                                                                                                                                                                                                                                                               |
| -------------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Source Name          | string          | Yes      | A name for the new source, as it will appear in the RudderStack dashboard.                                                                                                                                                                                                                                |
| Source Type          | select (string) | Yes      | What will send events to this source. Choose HTTP for server-to-server calls, or the SDK that matches your app. Available values: HTTP, Javascript, Node, Java, Python, Go, Ruby, PHP, DotNet, Rust, Android, iOS, android\_kotlin, ios\_swift, ReactNative, Flutter, Cordova, Unity, AMP. Default: HTTP. |
| Enabled              | boolean         | No       | Turn the source on straight away. A disabled source rejects events with a 404.                                                                                                                                                                                                                            |
| Source Config (JSON) | textarea        | No       | Advanced. Extra source settings as a JSON object. Leave blank for the source types offered here.                                                                                                                                                                                                          |

#### Outputs

| Field       | Type    | Description                                                                                                                        |
| ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Source ID   | string  | The id of the new source in RudderStack.                                                                                           |
| Write Key   | string  | The write key for sending events to this source. Treat it like a password: anyone holding it can write events into your workspace. |
| Source Name | string  | The name RudderStack recorded for the source.                                                                                      |
| Source Type | string  | The source type RudderStack recorded.                                                                                              |
| Enabled     | boolean | Whether the new source is accepting events.                                                                                        |
| Created At  | string  | When RudderStack created the source.                                                                                               |

### List Destinations

See the destinations your RudderStack workspace sends event data to, and whether each one is switched on.

#### Inputs

| Field                | Type            | Required | Description                                                                                                                                                          |
| -------------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Destination Type     | select (string) | No       | Only show destinations of one type. Pick from the types already set up in your workspace, or leave blank for all of them. Options load from the selected connection. |
| Maximum Destinations | integer         | No       | How many destinations to return at most. Minimum: 1. Maximum: 200. Default: 25.                                                                                      |
| Continue From        | string          | No       | Advanced. Paste the 'Next Cursor' from a previous run to carry on where it stopped.                                                                                  |

#### Outputs

| Field              | Type          | Description                                                                                                           |
| ------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------- |
| Destinations       | object\_array | The destinations that matched, with their type and enabled state.                                                     |
| Total In Workspace | integer       | How many destinations RudderStack reports in the workspace in total, which can be more than the number returned here. |
| Returned           | integer       | How many destinations this run actually returned after any filtering.                                                 |
| More Available     | boolean       | True when RudderStack says there are more destinations than this run returned.                                        |
| Next Cursor        | string        | Pass this back into 'Continue From' on the next run to get the following page.                                        |

## Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/rudderstack.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
