PostHog Tool

Connection Setup Guide

PostHog is an all-in-one product analytics platform. This tool allows an agent to interact with your PostHog instance to capture events, manage user data, and retrieve insights.

Key Use Cases

  • Event Tracking: Capture events from backend processes or other services to get a complete picture of user activity. For example, logging a premium_subscription_started event when a payment is successfully processed.
  • User Identification: Create or update user profiles with custom attributes, enriching your analytics data. For instance, setting a user's company name or subscription plan.
  • Feature Flag Evaluation: Check the status of a feature flag for a given user, allowing the agent to dynamically alter its behavior based on your rollout rules.
  • Data Retrieval: List product insights or find users (persons) to inform decisions or provide context for other tasks.

posthog_tool.capture_event

Captures a custom event in PostHog, which can be used for tracking user actions or system events.

Parameters

NameTypeDescription
distinct_id string A unique identifier for the user or entity associated with the event.
event string The name of the event to capture. Recommended format: '[object] [verb]' (e.g., 'user signed_up').
properties string Optional: A JSON string of key-value pairs to send with the event. 
curl -X POST https://toolstream.dev/v1/tools/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "posthog_tool.capture_event",
    "arguments": {
      "distinct_id": {
        "type": "string",
        "description": "A unique identifier for the user or entity associated with the event."
      },
      "event": {
        "type": "string",
        "description": "The name of the event to capture. Recommended format: '[object] [verb]' (e.g., 'user signed_up')."
      },
      "properties": {
        "type": "string",
        "description": "Optional: A JSON string of key-value pairs to send with the event."
      }
    }
  }
}'
import requests
import json

API_KEY = "YOUR_API_KEY"
TOOLSTREAM_URL = "https://toolstream.dev/v1/tools/execute"

payload = {
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "posthog_tool.capture_event",
    "arguments": {
      "distinct_id": {
        "type": "string",
        "description": "A unique identifier for the user or entity associated with the event."
      },
      "event": {
        "type": "string",
        "description": "The name of the event to capture. Recommended format: '[object] [verb]' (e.g., 'user signed_up')."
      },
      "properties": {
        "type": "string",
        "description": "Optional: A JSON string of key-value pairs to send with the event."
      }
    }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(TOOLSTREAM_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)

posthog_tool.identify_user

Sets or updates properties for a user profile in PostHog. This is used to add details about your users.

Parameters

NameTypeDescription
distinct_id string A unique identifier for the user whose profile is being updated.
properties string A JSON string of key-value pairs to set on the user's profile. 
curl -X POST https://toolstream.dev/v1/tools/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "posthog_tool.identify_user",
    "arguments": {
      "distinct_id": {
        "type": "string",
        "description": "A unique identifier for the user whose profile is being updated."
      },
      "properties": {
        "type": "string",
        "description": "A JSON string of key-value pairs to set on the user's profile."
      }
    }
  }
}'
import requests
import json

API_KEY = "YOUR_API_KEY"
TOOLSTREAM_URL = "https://toolstream.dev/v1/tools/execute"

payload = {
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "posthog_tool.identify_user",
    "arguments": {
      "distinct_id": {
        "type": "string",
        "description": "A unique identifier for the user whose profile is being updated."
      },
      "properties": {
        "type": "string",
        "description": "A JSON string of key-value pairs to set on the user's profile."
      }
    }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(TOOLSTREAM_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)

posthog_tool.alias_user

Creates an alias, merging two distinct IDs into a single user profile in PostHog.

Parameters

NameTypeDescription
previous_id string The old or anonymous distinct ID.
distinct_id string The new or identified distinct ID to merge the previous ID into. 
curl -X POST https://toolstream.dev/v1/tools/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "posthog_tool.alias_user",
    "arguments": {
      "previous_id": {
        "type": "string",
        "description": "The old or anonymous distinct ID."
      },
      "distinct_id": {
        "type": "string",
        "description": "The new or identified distinct ID to merge the previous ID into."
      }
    }
  }
}'
import requests
import json

API_KEY = "YOUR_API_KEY"
TOOLSTREAM_URL = "https://toolstream.dev/v1/tools/execute"

payload = {
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "posthog_tool.alias_user",
    "arguments": {
      "previous_id": {
        "type": "string",
        "description": "The old or anonymous distinct ID."
      },
      "distinct_id": {
        "type": "string",
        "description": "The new or identified distinct ID to merge the previous ID into."
      }
    }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(TOOLSTREAM_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)

posthog_tool.check_feature_flag

Checks if a feature flag is enabled for a given user. Returns True or False.

Parameters

NameTypeDescription
distinct_id string The distinct ID of the user to check the flag for.
flag_key string The key of the feature flag to evaluate. 
curl -X POST https://toolstream.dev/v1/tools/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "posthog_tool.check_feature_flag",
    "arguments": {
      "distinct_id": {
        "type": "string",
        "description": "The distinct ID of the user to check the flag for."
      },
      "flag_key": {
        "type": "string",
        "description": "The key of the feature flag to evaluate."
      }
    }
  }
}'
import requests
import json

API_KEY = "YOUR_API_KEY"
TOOLSTREAM_URL = "https://toolstream.dev/v1/tools/execute"

payload = {
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "posthog_tool.check_feature_flag",
    "arguments": {
      "distinct_id": {
        "type": "string",
        "description": "The distinct ID of the user to check the flag for."
      },
      "flag_key": {
        "type": "string",
        "description": "The key of the feature flag to evaluate."
      }
    }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(TOOLSTREAM_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)

posthog_tool.list_insights

Retrieves a list of all insights (graphs, charts, etc.) saved in the project.

This tool takes no parameters.

curl -X POST https://toolstream.dev/v1/tools/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "posthog_tool.list_insights",
    "arguments": {
    "arg": "value"
  }
  }
}'
import requests
import json

API_KEY = "YOUR_API_KEY"
TOOLSTREAM_URL = "https://toolstream.dev/v1/tools/execute"

payload = {
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "posthog_tool.list_insights",
    "arguments": {
    "arg": "value"
  }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(TOOLSTREAM_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)

posthog_tool.list_persons

Retrieves a list of persons (users) from the project. Can be filtered by email or distinct_id.

Parameters

NameTypeDescription
email string Filter persons by a specific email address.
distinct_id string Filter persons by a specific distinct ID. 
curl -X POST https://toolstream.dev/v1/tools/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "posthog_tool.list_persons",
    "arguments": {
      "email": {
        "type": "string",
        "description": "Filter persons by a specific email address."
      },
      "distinct_id": {
        "type": "string",
        "description": "Filter persons by a specific distinct ID."
      }
    }
  }
}'
import requests
import json

API_KEY = "YOUR_API_KEY"
TOOLSTREAM_URL = "https://toolstream.dev/v1/tools/execute"

payload = {
  "connection_name": "YOUR_CONNECTION_NAME",
  "tool_call": {
    "name": "posthog_tool.list_persons",
    "arguments": {
      "email": {
        "type": "string",
        "description": "Filter persons by a specific email address."
      },
      "distinct_id": {
        "type": "string",
        "description": "Filter persons by a specific distinct ID."
      }
    }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(TOOLSTREAM_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)