Workflow Integrations

n8n Nodes

Connect Alephant AI Gateway and analytics to n8n workflows
View as Markdown

Alephant provides two n8n community node packages for workflow automation:

PackageNodeUse it for
@alephantai/n8n-nodes-alephant-aiAlephant Cost ControlSend chat completion requests through Alephant with Virtual Key authentication, model routing, token tracking, request attribution, and cost-control policies.
@alephantai/n8n-nodes-alephant-analyticsAlephant AI AnalyticsRead 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:

$N8N_COMMUNITY_PACKAGES_ENABLED=true

If your deployment installs community packages with npm, install both packages:

$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 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.
FieldRequiredDefaultNotes
Virtual KeyYesNoneThe full Alephant Virtual Key value. It is sent as a Bearer token.
Workspace IDNoEmptyUsed by Request Log Detail lookups. If empty, the analytics node tries the incoming item and then the Alephant Scope API.
Gateway Base URLNohttps://ai.alephant.io/v1Used by Alephant Cost Control and by the credential test.
SaaS Base URLNohttps://alephant.ioUsed by Virtual Key-scoped Cockpit usage APIs.
Analytics Base URLNohttps://analytics.alephant.ioUsed 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

OperationWhat it does
Chat CompletionSends a chat completion request through Alephant AI Gateway.

Parameters

ParameterNotes
ModelModel name available to the configured Alephant workspace, for example gpt-4o-mini.
Input ModeChoose Prompt for a single user prompt or Messages JSON for an OpenAI-compatible messages array.
PromptUsed when Input Mode is Prompt.
MessagesUsed when Input Mode is Messages JSON. Each message needs string role and content fields.
TemperatureOptional model temperature.
Max TokensOptional maximum completion token count.
Response FormatText or JSON Object. JSON Object sends response_format: { "type": "json_object" }.
MetadataOptional JSON object. It is sent only when Additional Options includes "store": true.
Additional OptionsOptional JSON object merged into the chat completion request, excluding core fields managed by the node.

Prompt Example

Write a one sentence summary of why AI cost attribution matters.

Messages JSON Example

1[
2  {
3    "role": "system",
4    "content": "You write concise workflow summaries."
5  },
6  {
7    "role": "user",
8    "content": "Summarize the latest workflow item."
9  }
10]

Output

The node returns a normalized object with the raw provider response and convenient top-level fields:

1{
2  "raw": {
3    "id": "chatcmpl_...",
4    "choices": []
5  },
6  "text": "AI cost attribution matters because it shows which workflows and teams drive spend.",
7  "usage": {
8    "prompt_tokens": 18,
9    "completion_tokens": 17,
10    "total_tokens": 35
11  },
12  "model": "gpt-4o-mini",
13  "requestId": "9e3d...",
14  "requestLogId": "9e3d...",
15  "finishReason": "stop"
16}

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

OperationParametersWhat it reads
ScopeNoneWorkspace and Virtual Key scope from /api/v1/cockpit/scope.
Budget StatusPeriodBudget status for the selected period.
Usage SummaryPeriodUsage, request, token, and cost summary for the selected period.
Daily CostsPeriodDaily cost series for the selected period.
Cost by ModelPeriodCost grouped by model for the selected period.
Recent RequestsLimit, OffsetRecent Gateway requests for the Virtual Key scope.
Request Log DetailRequest Log ID, Workspace ID, Request Log Max AttemptsDetail 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:

{{$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.

TemplateFileWhat it demonstrates
Alephant Cost Control + AI Analytics Examplesalephant-example-workflow.jsonA manual trigger that runs an Alephant Cost Control chat completion and a 7-day analytics summary side by side.
Alephant Cost Control Request Cost Trackingalephant-ai-request-cost-workflow.jsonA 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.

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.

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.