> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # n8n Nodes > Installation, credentials, node parameters, and workflow templates for the Alephant n8n community nodes Alephant provides two n8n community node packages for workflow automation: | Package | Node | Use it for | | ------------------------------------------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `@alephantai/n8n-nodes-alephant-ai` | **Alephant Cost Control** | Send chat completion requests through Alephant with Virtual Key authentication, model routing, token tracking, request attribution, and cost-control policies. | | `@alephantai/n8n-nodes-alephant-analytics` | **Alephant AI Analytics** | Read Virtual Key-scoped usage, budget, cost, recent request, and request-log data from Alephant. | Install both packages when you want a workflow to make an AI request and then inspect its usage or request-log details. Both nodes use the same **Alephant Virtual Key** credential. ## Installation In n8n: 1. Go to **Settings** > **Community nodes**. 2. Select **Install**. 3. Install `@alephantai/n8n-nodes-alephant-ai`. 4. Install `@alephantai/n8n-nodes-alephant-analytics`. 5. Restart n8n if your deployment requires a restart after community node installation. For self-hosted n8n deployments, make sure community packages are enabled: ```bash N8N_COMMUNITY_PACKAGES_ENABLED=true ``` If your deployment installs community packages with npm, install both packages: ```bash npm install @alephantai/n8n-nodes-alephant-ai npm install @alephantai/n8n-nodes-alephant-analytics ``` ## Credential Both packages register and use the **Alephant Virtual Key** credential. Create a Virtual Key in Alephant before configuring n8n: 1. Open the [Alephant dashboard](https://alephant.io/) and sign in to your workspace. 2. Add an upstream provider API key as a Master Key. 3. Create an Agent for the n8n workflow or application that will send AI traffic. 4. Copy the Agent's Virtual Key. 5. In n8n, create a new **Alephant Virtual Key** credential and paste the key into **Virtual Key**. | Field | Required | Default | Notes | | -------------------- | -------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `Virtual Key` | Yes | None | The full Alephant Virtual Key value. It is sent as a Bearer token. | | `Workspace ID` | No | Empty | Used by **Request Log Detail** lookups. If empty, the analytics node tries the incoming item and then the Alephant Scope API. | | `Gateway Base URL` | No | `https://ai.alephant.io/v1` | Used by **Alephant Cost Control** and by the credential test. | | `SaaS Base URL` | No | `https://alephant.io` | Used by Virtual Key-scoped Cockpit usage APIs. | | `Analytics Base URL` | No | `https://analytics.alephant.io` | Used by request-log detail lookups. | Keep the default base URLs for production. Override them only for staging, local, self-hosted, or dedicated Alephant deployments. The credential test calls the Alephant Gateway `/models` endpoint with your Virtual Key. A successful test means n8n can authenticate to the gateway. ## Alephant Cost Control The **Alephant Cost Control** node is provided by `@alephantai/n8n-nodes-alephant-ai`. It sends `POST /chat/completions` requests through Alephant. The request can use an OpenAI-compatible shape, but Alephant's role is broader than proxying the model call: it handles Virtual Key authentication, routing, budget enforcement, usage logging, and request attribution for the workflow or agent run. ### Operation | Operation | What it does | | ----------------- | ------------------------------------------------------------ | | `Chat Completion` | Sends a chat completion request through Alephant AI Gateway. | ### Parameters | Parameter | Notes | | -------------------- | -------------------------------------------------------------------------------------------------------- | | `Model` | Model name available to the configured Alephant workspace, for example `gpt-4o-mini`. | | `Input Mode` | Choose `Prompt` for a single user prompt or `Messages JSON` for an OpenAI-compatible messages array. | | `Prompt` | Used when `Input Mode` is `Prompt`. | | `Messages` | Used when `Input Mode` is `Messages JSON`. Each message needs string `role` and `content` fields. | | `Temperature` | Optional model temperature. | | `Max Tokens` | Optional maximum completion token count. | | `Response Format` | `Text` or `JSON Object`. `JSON Object` sends `response_format: { "type": "json_object" }`. | | `Metadata` | Optional JSON object. It is sent only when `Additional Options` includes `"store": true`. | | `Additional Options` | Optional JSON object merged into the chat completion request, excluding core fields managed by the node. | ### Prompt Example ```text Write a one sentence summary of why AI cost attribution matters. ``` ### Messages JSON Example ```json [ { "role": "system", "content": "You write concise workflow summaries." }, { "role": "user", "content": "Summarize the latest workflow item." } ] ``` ### Output The node returns a normalized object with the raw provider response and convenient top-level fields: ```json { "raw": { "id": "chatcmpl_...", "choices": [] }, "text": "AI cost attribution matters because it shows which workflows and teams drive spend.", "usage": { "prompt_tokens": 18, "completion_tokens": 17, "total_tokens": 35 }, "model": "gpt-4o-mini", "requestId": "9e3d...", "requestLogId": "9e3d...", "finishReason": "stop" } ``` `requestId` and `requestLogId` are generated by the node and sent to Alephant Gateway as `x-request-id`. Pass `requestLogId` into **Alephant AI Analytics** to look up the matching request log. ## Alephant AI Analytics The **Alephant AI Analytics** node is provided by `@alephantai/n8n-nodes-alephant-analytics`. It reads Virtual Key-scoped usage and request-log data from Alephant. The node is also marked as usable as an n8n tool, so agent workflows can call it when they need usage or request context. ### Operations | Operation | Parameters | What it reads | | -------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------- | | `Scope` | None | Workspace and Virtual Key scope from `/api/v1/cockpit/scope`. | | `Budget Status` | `Period` | Budget status for the selected period. | | `Usage Summary` | `Period` | Usage, request, token, and cost summary for the selected period. | | `Daily Costs` | `Period` | Daily cost series for the selected period. | | `Cost by Model` | `Period` | Cost grouped by model for the selected period. | | `Recent Requests` | `Limit`, `Offset` | Recent Gateway requests for the Virtual Key scope. | | `Request Log Detail` | `Request Log ID`, `Workspace ID`, `Request Log Max Attempts` | Detail for a single request log from the Analytics API. | `Period` supports `24 Hours`, `7 Days`, `30 Days`, and `90 Days`. ### Request Log Detail Use **Request Log Detail** after an AI request when you need request-level cost, latency, token, model, or provider data. The default **Request Log ID** expression is: ```text {{$json.requestLogId || $json.requestId || ""}} ``` Workspace ID is resolved in this order: 1. The node's **Workspace ID** parameter. 2. The incoming item's `workspaceId`, `workspace_id`, or `xWorkspaceId`. 3. The **Workspace ID** saved in the **Alephant Virtual Key** credential. 4. The Alephant Scope API. If none of those sources returns a workspace ID, the node errors because the Analytics request-log endpoint needs workspace scope. Add a **Wait** node before request-log detail lookups if your workflow queries immediately after an AI request and log ingestion has not completed yet. ## Example Workflow Templates Use these workflow JSON files to try the nodes quickly after installing both packages. Each template can be imported into n8n and then configured with your own **Alephant Virtual Key** credential. | Template | File | What it demonstrates | | --------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Alephant Cost Control + AI Analytics Examples | `alephant-example-workflow.json` | A manual trigger that runs an Alephant Cost Control chat completion and a 7-day analytics summary side by side. | | Alephant Cost Control Request Cost Tracking | `alephant-ai-request-cost-workflow.json` | A full flow that builds an AI request, waits for the request log, fetches request log detail, and summarizes token and cost fields. | ### Alephant Cost Control + AI Analytics Examples This template is the quickest way to confirm that the installed community nodes can connect to Alephant. It starts from a manual trigger and runs two independent Alephant nodes: * **Alephant Cost Control - Chat Completion:** sends a sample prompt to Alephant Gateway with `gpt-4o-mini`. * **Alephant AI Analytics - 7 Day Summary:** reads recent Virtual Key usage data for the last 7 days. Download example workflow JSON ### Alephant Cost Control Request Cost Tracking This template demonstrates how to connect an AI request to its matching Alephant request log and extract cost information after the request completes. The workflow runs in this order: 1. **Build AI Request** creates a prompt and model payload. 2. **Alephant Cost Control - Chat Completion** sends the request through Alephant Gateway. 3. **Wait for Request Log** pauses briefly so the gateway request log can be written. 4. **Alephant AI Analytics - Request Log Detail** fetches the matching request log by `requestLogId` or `requestId`. 5. **Summarize Cost** returns a compact object with the request log ID, model, prompt, response text, token usage, cost, currency, and raw request log. Use this template when you want to build budget-aware workflows, cost dashboards, approval flows, or alerts around individual AI requests. Select the same **Alephant Virtual Key** credential on both Alephant nodes. If the workflow does not receive a workspace ID from the prior node, the analytics node resolves workspace scope from the configured credential or the Scope API. Download request cost workflow JSON To use a template in n8n: 1. Install `@alephantai/n8n-nodes-alephant-ai`. 2. Install `@alephantai/n8n-nodes-alephant-analytics`. 3. Import the workflow JSON file into n8n. 4. Open each Alephant node and choose the required **Alephant Virtual Key** credential. 5. Run the workflow with **Test workflow** or execute the nodes one at a time. ## Typical Workflows * Route AI tasks through Alephant Gateway from n8n with the **Alephant Cost Control** node. * Run **Alephant AI Analytics** before expensive workflow branches to inspect recent spend or budget status. * Join an AI node's `requestLogId` with **Request Log Detail** to create cost-aware notifications, audit trails, approval flows, or dashboards.