Amplitude Connector Guide

The Amplitude connector lets you send product and business events from Tealfabric workflows into Amplitude with consistent authentication and payload structure. This guide shows how to configure the connector, validate connectivity, and run common event ingestion and export patterns so your analytics pipeline remains reliable in production.

When to use this connector

Use this connector when your ProcessFlow automations need to track user behavior, feature adoption, operational milestones, or lifecycle updates in Amplitude. It is a strong fit when analytics events are generated in backend workflows instead of browser-only instrumentation. A stable event schema and consistent identifiers make downstream dashboards and cohort logic more trustworthy.

Prerequisites

Before creating the integration, confirm that you have an Amplitude project with valid ingestion credentials and that your team has agreed on required event fields. You should decide how user_id, event_type, and core event properties are mapped from workflow data so each run produces usable analytics records. Preparing this schema up front reduces cleanup work later.

Configuration reference

Connector settings are stored in the integration configuration and reused across executions. Keep secret values in secure storage and rotate them according to your environment policy.

• api_key (required): Amplitude project API key for HTTP ingestion.
• base_url (optional): API base URL, typically https://api2.amplitude.com.
• api_secret (optional): Additional secret for endpoints that require it.
• timeout_seconds (optional): Request timeout for connector operations.

Send events to Amplitude

The send operation is the primary integration path and supports single or batched event payloads. The examples below submit events through Tealfabric so you can track workflow outcomes and user behavior in one consistent pattern.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type AmplitudeSendResult = {
  code?: number;
  events_ingested?: number;
  payload_size_bytes?: number;
};

async function sendAmplitudeEvents(
  integrationId: string
): Promise<AmplitudeSendResult> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "send",
        events: [
          {
            user_id: "user-123",
            event_type: "signup_completed",
            time: Date.now(),
            event_properties: {
              signup_method: "email",
              plan: "pro",
            },
            user_properties: {
              account_tier: "paid",
            },
          },
          {
            user_id: "user-123",
            event_type: "feature_used",
            time: Date.now(),
            event_properties: {
              feature: "workflow_templates",
            },
          },
        },
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as {
    success?: boolean;
    data?: { message_count?: number; data?: AmplitudeSendResult; response?: AmplitudeSendResult };
  };
  if (!payload.data) throw new Error("Missing Amplitude response payload");
  return payload.data;
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "send",
    "events": [
      {
        "user_id": "user-123",
        "event_type": "signup_completed",
        "time": 1746706800000,
        "event_properties": {
          "signup_method": "email",
          "plan": "pro"
        }
      }
    ]
  }'

{
  "success": true,
  "data": {
    "message_count": 1,
    "data": {
      "code": 200,
      "events_ingested": 1,
      "payload_size_bytes": 248
    },
    "response": {
      "code": 200,
      "events_ingested": 1,
      "payload_size_bytes": 248
    }
  }
}

Export event data when needed

Amplitude is typically ingestion-first, but you may still need to retrieve historical records for reconciliation or reporting workflows. Use the receive operation with explicit date windows and controlled limits so data extraction stays predictable and cost-aware.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type ExportRecord = {
  event_type?: string;
  user_id?: string;
  event_time?: string;
};

async function exportAmplitudeEvents(integrationId: string): Promise<ExportRecord[]> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "receive",
        endpoint: "export",
        start: "20260501",
        end: "20260501",
        query: {
          limit: 1000
        },
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as {
    success?: boolean;
    data?: { message_count?: number; data?: ExportRecord[]; total_size?: number };
  };
  if (!payload.data?.data) throw new Error("Missing export payload");
  return payload.data.data;
}

Validate and troubleshoot connector health

Run test before promoting changes to production, especially after rotating keys or changing project settings in Amplitude. If requests fail, verify credentials first, then validate payload fields and timestamp formatting. Structured retries with bounded backoff help handle temporary failures while protecting your ingestion quotas.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "test"
  }'

{
  "success": true,
  "data": {
    "message": "Amplitude connection test successful",
    "details": {
      "api_base_url": "https://api2.amplitude.com"
    }
  }
}

Batch event ingestion

Use batch when a workflow emits more than a few events at once. The connector chunks requests at 1000 events per Amplitude HTTP API call and applies local 10 req/sec throttling between calls.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "batch",
    "events": [
      {
        "user_id": "user-123",
        "event_type": "workflow_step_completed",
        "time": 1746706800000
      }
    ]
  }'

{
  "success": true,
  "data": {
    "message_count": 1,
    "total_events": 1,
    "successful_batches": 1,
    "results": [
      {
        "index": 0,
        "success": true,
        "result": {
          "success": true,
          "message_count": 1,
          "data": { "code": 200, "events_ingested": 1 },
          "response": { "code": 200, "events_ingested": 1 }
        }
      }
    ]
  }
}

Additional references

For deeper endpoint and schema details, use the official Amplitude documentation: Amplitude API documentation and HTTP API v2 reference. Keeping your Tealfabric payload structure aligned with the current Amplitude schema ensures long-term compatibility.