Particl Market Research

Get detailed information about a specific company.

Args: company_id: The Particl company ID (e.g., '1234567')

Returns: Company profile including name, domain, country, vertical, start date, product count, whether product-level data exists (has_product_data), and top product categories.

The has_product_data field indicates whether the company has product-level data. When has_sales_data is false, sales fields are not populated for this company. When has_pricing_data is false, pricing fields are not populated.

Get promotional events for a company — product launches, sales, restocks, price changes, and discounts — with associated marketing assets and products. Use search_companies first to find the company_id.

Args: company_id: The Particl company ID (e.g., '1234567') - required start_date: Start of date range (ISO format, e.g., '2025-01-01'). Defaults to ~30 days ago. end_date: End of date range (ISO format, e.g., '2025-01-31'). Defaults to ~2 days ago. event_types: Filter by event type(s). Common values: 'Promotion', 'Product Release', 'Special Event', 'Collaboration', 'Restock'. Many other values exist — call without this filter first to discover available types for a company. channels: Filter by marketing channel(s). Options: 'email', 'instagram_post', 'facebook_ads', 'sms', 'homepage_screenshot' page_size: Number of results (default 10, max 100) page: Page number for pagination (0-indexed, default 0)

Returns: List of promotional events with associated marketing assets and products

List a company's marketing assets — emails, Instagram posts, Facebook/Meta ads, SMS messages, and homepage screenshots. Use search_companies first to find the company_id. .

Args: company_id: The Particl company ID (e.g., '1234567') - required asset_types: Filter by asset type(s). Options: 'email', 'instagram_post', 'facebook_ads', 'sms', 'homepage_screenshot'. Defaults to all types. start_date: Start of date range (ISO format, e.g., '2025-01-01'). Defaults to ~30 days ago. end_date: End of date range (ISO format, e.g., '2025-01-31'). Defaults to ~2 days ago. page_size: Number of results (default 25, max 100) page: Page number for pagination (0-indexed, default 0)

Returns: List of marketing assets with content, engagement metrics, and metadata. Assets include product_ids when available — use these with get_company_products to look up sales and revenue data for the featured products.

Get aggregated marketing engagement statistics for a company — posting frequency by type, average likes, engagement rate, most liked post, and posting hour distribution. Use search_companies first to find the company_id.

Args: company_id: The Particl company ID (e.g., '1234567') - required

Returns: total_assets: total number of marketing assets in the last 30 days assets_by_type: dict of asset counts keyed by type (e.g. {"instagram_post": 42, "email": 10}) engagement_metrics: dict of {avg_likes, avg_comments} keyed by type posting_hours: dict of hour-frequency lists keyed by type estimated_reach: dict of average follower counts keyed by type (e.g. {"instagram_post": 50000.0}) avg_likes: dict of average likes keyed by type (e.g. {"instagram_post": 1200.5}) engagement_rate: dict of engagement rate percentages keyed by type (e.g. {"instagram_post": 4.2}) most_liked_post: dict of most liked post details keyed by type

Deep-dive into a specific company's product catalog. This is the primary tool for company-level analysis — supports full pagination and custom date ranges for sales data. Use search_companies first to find the company_id.

Args: company_id: The Particl company ID (e.g., '1234567') - required. Use search_companies to find this. product_type_id: Product type UUID from get_product_types. Pass the product_type_id value, not the name. keyword: Filter by keyword/tag (e.g., 'wool', 'recycled'). Searches product tags only, NOT product titles. Use title_search to search by title. title_search: Search products by title (e.g., 'tank top', 'winter jacket'). Matches against product display title. brand: Filter by brand name min_price: Minimum price filter max_price: Maximum price filter sort_by: Sort by 'sales_revenue' (default), 'sales_volume', 'price', or 'launch_date' sort_direction: 'desc' (default) or 'asc' page_size: Number of results (default 25, max 100) page: Page number for pagination (0-indexed, default 0) start_date: Start of sales data aggregation window (ISO format, e.g., '2025-01-01'). Defaults to ~30 days ago. end_date: End of sales data aggregation window (ISO format, e.g., '2025-01-31'). Defaults to today.

Returns: List of products from the specified company with pricing, sales estimates, and metadata

Check your remaining export credits.

Returns: Credit balance including total limit, used, and remaining credits

Get pricing analysis for a market or category.

Args: product_type_id: Product type UUID from get_product_types. Pass the product_type_id value, not the name. keyword: Filter by keyword/tag end_date: End of trailing 30-day analysis window (ISO format, e.g., '2025-01-15'). Defaults to ~2 days ago.

Returns: Pricing summary with average, median, range, and distribution buckets

Get aggregated market-level sales data with monthly timeseries.

Returns total market revenue and volume, plus monthly timeseries showing how the market is trending over time. Use with get_market_top_companies and get_market_top_products for complete market analysis.

Args: product_type_id: Product type UUID from get_product_types. Pass the product_type_id value, not the name. keyword: Filter by keyword/tag (e.g., 'sustainable', 'organic') end_date: End of trailing analysis window (ISO format, e.g., '2025-01-15'). Defaults to ~2 days ago.

Returns: Market sales summary with total revenue/volume and monthly timeseries

Get top-performing companies in a market or category. High-level view, no pagination.

Args: product_type_id: Product type UUID from get_product_types. Pass the product_type_id value, not the name. keyword: Filter by keyword/tag (e.g., 'luxury', 'athleisure') end_date: End of trailing 30-day analysis window (ISO format, e.g., '2025-01-15'). Defaults to ~2 days ago.

Returns: List of top companies with revenue and sales volume estimates

Get best-selling products in a market or category. High-level view, no pagination.

Args: product_type_id: Product type UUID from get_product_types. Pass the product_type_id value, not the name. keyword: Filter by keyword/tag (e.g., 'sustainable', 'organic') end_date: End of trailing 30-day analysis window (ISO format, e.g., '2025-01-15'). Defaults to ~2 days ago.

Returns: List of top products with sales estimates, pricing, and product details

Get full details of a specific marketing asset — email content, social post with engagement metrics, ad creative with cards, or homepage screenshot.

Args: company_id: The Particl company ID (e.g., '1234567') - required asset_id: The asset ID - required

Returns: Full asset details including content, engagement metrics, metadata, and product_ids when available. Use product_ids with get_company_products to look up sales and revenue data for the featured products.

Get product data broken down by a specific attribute (color, brand, material, keyword, gender, or location). .

Useful for understanding product mix — e.g., which colors sell best, which brands dominate, what materials are most popular.

Args: company_id: The Particl company ID (e.g., '1234567') - required. Use search_companies to find this. breakdown_type: What to break down by. One of: 'keyword', 'material', 'colors', 'brands', 'gender', 'locations'. product_type_id: Product type UUID from get_product_types to filter by category. keyword: Filter by keyword/tag (e.g., 'sustainable'). Searches product tags only. start_date: Start of date range (ISO format, e.g., '2025-01-01'). Defaults to ~30 days ago. end_date: End of date range (ISO format, e.g., '2025-01-31'). Defaults to today.

Returns: List of breakdown buckets with name, count, sales_revenue, sales_volume, and pricing

Get full details for a specific product.

Returns comprehensive product information including pricing, brand, gender, ratings, reviews, images, materials, keywords, and category data. Use get_company_products first to find product_ids.

Args: company_id: The Particl company ID (e.g., '1234567') - required product_id: The product ID - required. Get this from get_company_products or get_market_top_products.

Returns: Full product profile with metadata, ratings, and attributes

Browse the product type taxonomy to discover valid categories for filtering.

Use the returned product_type_id values in other tools' product_type_id parameter.

How to use: 1. Call with no parameters to get root-level categories 2. Pass a product_type_id as parent_product_type_id to see its subcategories 3. Keep drilling deeper until you find the right category 4. Use the chosen product_type_id as the product_type_id filter in other tools

Args: parent_product_type_id: Get child categories under this product type. Omit to get root-level categories.

Returns: List of product type categories with product_type_id and name

Get variant-level data for a specific product (colors, sizes, individual pricing and sales). Use get_company_products first to find product_ids.

Args: company_id: The Particl company ID (e.g., '1234567') - required product_id: The product ID - required. Get this from get_company_products or get_market_top_products. start_date: Start of sales data window (ISO format, e.g., '2025-01-01'). Defaults to ~30 days ago. end_date: End of sales data window (ISO format, e.g., '2025-01-31'). Defaults to today.

Returns: List of product variants with color, size, pricing, and sales data

Get historical sales timeseries data for a company or a single product.

Returns daily, weekly, or monthly sales data points showing revenue, volume, pricing, and inventory over time. Essential for understanding trends, seasonality, and growth. Pass product_id to get timeseries for a single product, or omit for company-wide data.

Args: company_id: The Particl company ID (e.g., '1234567') - required. Use search_companies to find this. product_id: Optional product ID to get timeseries for a single product. Get this from get_company_products or get_market_top_products. product_type_id: Product type UUID from get_product_types to filter by category. keyword: Filter by keyword/tag (e.g., 'sustainable', 'organic'). Searches product tags only. start_date: Start of date range (ISO format, e.g., '2025-01-01'). Defaults to ~30 days ago. end_date: End of date range (ISO format, e.g., '2025-01-31'). Defaults to today. aggregation_type: Time granularity - 'daily', 'weekly', or 'monthly'. Auto-selected if omitted.

Returns: Timeseries data points with sales_revenue, sales_volume, avg_current_price, and totals

Search for companies by name or domain.

Args: search: Search term (company name or domain) page_size: Number of results to return (default 25, max 100) page: Page number for pagination (0-indexed, default 0) sort_by: Sort results by 'popularity' (default) or 'start_date' country_code: Filter by country code (default 'US'). Common values: 'US', 'CA', 'AU', 'GB'. Pass empty string to search all countries.

Returns: List of matching companies with their basic info