{ "version": "v1", "generated_at": "2026-09-10T21:16:24.410Z", "examples": [ { "title": "Credit summary", "category": "credits", "description": "Inspect the shared account credit pool, current API key usage, active search rate card, and billing semantics.", "request": { "range": "30d" }, "response": { "success": true, "owner_user_id": "owner_user_123", "credit_pool_scope": "account_owner", "range": { "key": "last_30_days", "start": "2026-03-05T00:00:00.000Z", "end": "2026-04-03T23:59:59.999Z" }, "current_api_key": { "id": "api_key_123", "name": "Production sourcing worker", "key_prefix": "carl_abcd1234", "scopes": [ "search", "enrich", "profiles-read", "communications" ], "status": "active", "last_used_at": "2026-04-03T18:12:55.000Z", "created_at": "2026-03-15T10:00:00.000Z" }, "current_key_usage": { "credits_used": 184, "units": 184, "preview_searches": 72, "full_searches": 98, "linkedin_lookups": 14 }, "account_credit_pool": { "totals": { "units": 421, "snapshot_credits": 421, "current_credits": 421, "snapshot_cost": 126.3 }, "breakdown": [ { "action_type": "search", "action_subtype": "results", "units": 210, "snapshot_credits": 210, "current_credits": 210, "snapshot_cost": 63, "applied_rule": { "action_type": "search", "action_subtype": "results", "units_per_credit": 1, "credits_per_unit": 1, "effective_at": "2026-03-01T00:00:00.000Z", "expires_at": null, "description": "Full search credits" } } ] }, "rate_card": { "conversion_rules": [ { "action_type": "search", "action_subtype": "preview", "units_per_credit": 1, "credits_per_unit": 1, "effective_at": "2026-08-21T00:00:00.000Z", "expires_at": null, "description": "Each completed preview search costs one credit" }, { "action_type": "search", "action_subtype": "results", "units_per_credit": 1, "credits_per_unit": 1, "effective_at": "2026-08-21T00:00:00.000Z", "expires_at": null, "description": "Each completed results search costs one credit" }, { "action_type": "search", "action_subtype": "batch_lookup", "units_per_credit": 100, "minimum_credits": 1, "effective_at": "2026-08-25T00:00:00.000Z", "expires_at": null, "description": "Non-empty batches cost max(1, successfully completed rows / 100) credits" }, { "action_type": "search", "action_subtype": "export", "units_per_credit": 100, "minimum_credits": 1, "effective_at": "2026-08-25T00:00:00.000Z", "expires_at": null, "description": "Non-empty exports cost max(1, completed rows / 100) credits" } ], "cost_rates": [ { "action_type": "search", "action_subtype": "preview", "model": null, "cost_per_unit": 0.15, "currency": "usd", "effective_at": "2026-03-01T00:00:00.000Z", "expires_at": null, "description": "Preview search internal cost" } ] }, "billing_semantics": [ { "operation": "people_search_results", "endpoint": "POST /api/v1/search/people", "scopes": [ "search" ], "billing_mode": "credit_event", "action_type": "search", "action_subtype": "results", "note": "Creates a full-search credit usage event." }, { "operation": "people_search_enrich", "endpoint": "POST /api/v1/search/people/enrich", "scopes": [ "enrich" ], "billing_mode": "updates_existing_search_event", "action_type": "search", "action_subtype": "results", "note": "Enrich updates the original full-search activity record and does not create a second standalone credit usage event." } ], "notes": [ "All API usage draws from the same account credit pool as in-app searches.", "current_key_usage reflects recorded credit events for this API key within the selected range." ] }, "curl": "curl -X GET \"https://api.supercarl.ai/api/v1/credits?range=30d\" \\\n -H \"X-API-Key: \"" }, { "title": "Communication capabilities", "category": "communications", "description": "Inspect which outbound channels are currently available for the acting user and target.", "request": { "x_profile_url": "https://x.com/benkeighran" }, "response": { "owner_user_id": "owner_user_123", "acting_user_id": "seat_user_456", "is_delegate": true, "resolved_target": { "id": "user_123", "name": "Sample Person", "x_profile_url": "https://x.com/benkeighran", "recipient_email": "sample@example.com" }, "channels": [ { "channel": "x_send_message", "can_send": true, "reason_code": "ready", "reason": "The acting user has an X browser session and the target resolves to an X profile.", "action_required": null, "fallback_channels": [ "gmail_send" ] } ], "supercarl": { "direct_message_available": false, "invite_available": false, "referral_available": true, "candidate_connectors": [ { "id": "connector_123", "name": "Warm Connector", "action_mode": "supercarl_referral", "path_score": 87 } ] } }, "curl": "curl -X POST https://api.supercarl.ai/api/v1/communications/capabilities \\\n -H \"X-API-Key: \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"x_profile_url\": \"https://x.com/benkeighran\"\n }'" }, { "title": "LinkedIn durable draft", "category": "communications", "description": "Save an MCP-session outreach draft without sending. Link macros are expanded before the draft is returned and stored for review.", "request": { "mode": "draft", "channel": "linkedin_send_message", "agent_session_id": "agent_session_uuid", "linkedin_profile_url": "https://www.linkedin.com/in/target-person/", "message": "Worth connecting on this? [JoinLink]" }, "response": { "id": "communication_123", "channel": "linkedin_send_message", "status": "completed", "dry_run": true, "result": { "outcome": "drafted", "draft": { "message": "Worth connecting on this? https://supercarl.ai/join/mdale/o/abc123", "assignment_id": "assignment_uuid", "assignment_target_id": "assignment_target_uuid" } } }, "curl": "curl -X POST https://api.supercarl.ai/api/v1/communications \\\n -H \"X-API-Key: \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"mode\": \"draft\",\n \"channel\": \"linkedin_send_message\",\n \"agent_session_id\": \"agent_session_uuid\",\n \"linkedin_profile_url\": \"https://www.linkedin.com/in/target-person/\",\n \"message\": \"Worth connecting on this? [JoinLink]\"\n }'" }, { "title": "X dry-run send", "category": "communications", "description": "Create a dry-run X communication record and inspect it later through the status endpoint or SSE stream.", "request": { "channel": "x_send_message", "x_profile_url": "https://x.com/benkeighran", "message": "Quick note from Super Carl.", "dry_run": true }, "response": { "id": "communication_123", "channel": "x_send_message", "status": "completed", "result": { "outcome": "dry_run" }, "task": null, "reasoning_lookup": { "context_type": null, "context_id": null, "task_id": null, "entry_id": null }, "events": [ { "sequence": 1, "event_type": "validated", "status": "queued" }, { "sequence": 3, "event_type": "completed", "status": "completed", "message": "Dry run completed without sending." } ], "artifacts": [], "webhook": { "url": null, "delivery_attempts": 0, "last_attempt_at": null, "last_status": null, "last_error": null } }, "curl": "curl -X POST https://api.supercarl.ai/api/v1/communications \\\n -H \"X-API-Key: \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"channel\": \"x_send_message\",\n \"x_profile_url\": \"https://x.com/benkeighran\",\n \"message\": \"Quick note from Super Carl.\",\n \"dry_run\": true\n }'" }, { "title": "LinkedIn lookup", "category": "people-search", "description": "Lookup a profile by LinkedIn username or full LinkedIn profile URL.", "request": { "linkedin_profile_url": "https://www.linkedin.com/in/reidhoffman/" }, "response": { "success": true, "search_id": null, "enrichable": false, "users": [ { "id": "user_123", "name": "Sample Person", "linkedin_url": "https://www.linkedin.com/in/reidhoffman", "supercarl_url": "https://supercarl.ai/profile/reidhoffman" } ], "search_metadata": { "strategy": "linkedin_lookup", "lookup": { "created": false, "profile_index_status": "indexed", "enrichment": { "status": "skipped" } } } }, "curl": "curl -X POST https://api.supercarl.ai/api/v1/search/people \\\n -H \"X-API-Key: \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"linkedin_profile_url\": \"https://www.linkedin.com/in/reidhoffman/\"\n }'" }, { "title": "Profile chunks (cached)", "category": "profiles", "description": "Fetch cached profile chunks without refreshing.", "request": null, "response": { "success": true, "user_id": "user_123", "chunks": [ { "id": "chunk_1", "chunk_type": "experience", "chunk_text": "Head of Growth at ExampleCo Description: Built outbound and lifecycle growth programs.", "chunk_metadata": { "title": "Head of Growth", "company": "ExampleCo", "start_year": 2022, "start_month": 1, "end_year": null, "end_month": null, "is_current": true, "date_range": "Jan 2022 - Present", "tenure_months": 51, "company_id": "company_123" } }, { "id": "chunk_2", "chunk_type": "post", "chunk_text": "Hiring GTM operators who know how to build repeatable pipeline in healthcare SaaS.", "chunk_metadata": { "post_url": "https://www.linkedin.com/feed/update/urn:li:activity:123", "post_date": "2026-03-01", "post_platform": "linkedin" } } ] }, "curl": "curl -X GET https://api.supercarl.ai/api/v1/profiles/user_123/chunks?posts_limit=10 \\\n -H \"X-API-Key: \"" }, { "title": "Profile text", "category": "profiles", "description": "Fetch profile text ready for LLM embeddings.", "request": null, "response": { "success": true, "user_id": "user_123", "text": { "mode": "full", "text": "Headline: Growth leader at ExampleCo\nSummary: ...", "posts_included": 5, "companies_included": 2 } }, "curl": "curl -X GET https://api.supercarl.ai/api/v1/profiles/user_123/text?mode=full&posts_limit=5 \\\n -H \"X-API-Key: \"" }, { "title": "Description search (auto-translated)", "category": "people-search", "description": "Run a natural language description that is auto-translated into AdvancedFilters.", "request": { "description": "VP of Sales at mid-size companies in San Francisco", "limit": 10, "offset": 0 }, "response": { "success": true, "search_id": "8c7fbf1a-5db5-4b15-9c76-6f4b3be3f7f4", "enrichable": true, "users": [ { "id": "user_123", "name": "Sample Person", "headline": "VP of Sales at ExampleCo", "location": "San Francisco Bay Area", "linkedin_url": "https://linkedin.com/in/example", "mutual_connections_count": 6, "social_proximity_score": 58, "social_proximity_band": "warm", "social_proximity_tier": "Warm", "best_intro_path_type": "supercarl_referral", "score_version": 7 } ], "pagination": { "limit": 10, "offset": 0, "total": 125, "hasMore": true }, "search_metadata": { "search_backend": "es", "description_snapshot": "VP of Sales at mid-size companies in San Francisco", "filters": { "summary": "VP of Sales in San Francisco at mid-size companies", "advanced": { "job_titles": { "include": [ "VP of Sales" ], "exclude": [], "mode": "must", "exact": false, "current_only": true }, "locations": { "include": [ "San Francisco Bay Area" ], "exclude": [], "radius_miles": 50, "strict": false, "scope": "current" } } } } }, "curl": "curl -X POST https://api.supercarl.ai/api/v1/search/people \\\n -H \"X-API-Key: \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"description\": \"VP of Sales at mid-size companies in San Francisco\",\n \"limit\": 10,\n \"offset\": 0\n }'" }, { "title": "Full people search", "category": "people-search", "description": "Run a full search with explicit AdvancedFilters and inline evidence_text for evaluator-friendly matching context.", "request": { "description": "Head of Growth in New York", "limit": 10, "offset": 0, "include_evidence_text": true, "evidence_text_mode": "full", "evidence_posts_limit": 5, "filters": { "job_titles": { "include": [ "Head of Growth" ], "exclude": [], "mode": "must", "exact": false, "current_only": true }, "locations": { "include": [ "New York, NY" ], "exclude": [], "radius_miles": 25, "strict": false, "scope": "current" } } }, "response": { "success": true, "search_id": "8c7fbf1a-5db5-4b15-9c76-6f4b3be3f7f4", "enrichable": true, "users": [ { "id": "user_123", "name": "Sample Person", "headline": "Growth lead at ExampleCo", "location": "New York, NY", "linkedin_url": "https://linkedin.com/in/example", "years_experience_months": 121, "current_role_tenure_months": 39, "average_role_tenure_months": 34, "evidence_text": "Profile:\nHeadline: Growth lead at ExampleCo\n\nExperience:\nHead of Growth at ExampleCo\nDates: Jan 2023 - Present\nCompany details: Size: 201-500; Industries: SaaS, Marketing Tech\nVP Growth at EarlierCo\nDates: Feb 2020 - Dec 2022\nCompany details: Size: 51-200; Industries: Healthcare, SaaS\n\nRecent posts:\nPost 1 | 2026-03-01: Building repeatable pipeline with healthcare revenue teams.", "evidence_text_mode": "full", "evidence_posts_included": 5, "evidence_companies_included": 2, "has_previous_correspondence": true, "previous_correspondence_count": 3, "previous_correspondence_last_sent_at": "2026-04-01T12:00:00.000Z", "mutual_connections_count": 3, "social_proximity_score": 41, "social_proximity_band": "some_signal", "social_proximity_tier": "Some signal", "best_intro_path_type": "manual_linkedin_intro", "score_version": 7 } ], "pagination": { "limit": 10, "offset": 0, "total": 125, "hasMore": true }, "search_metadata": { "search_backend": "es", "description_snapshot": "Head of Growth in New York", "filters": { "summary": "Head of Growth in New York", "advanced": { "job_titles": { "include": [ "Head of Growth" ], "exclude": [], "mode": "must", "exact": false, "current_only": true }, "locations": { "include": [ "New York, NY" ], "exclude": [], "radius_miles": 25, "strict": false, "scope": "current" } } } } }, "curl": "curl -X POST https://api.supercarl.ai/api/v1/search/people \\\n -H \"X-API-Key: \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"description\": \"Head of Growth in New York\",\n \"limit\": 10,\n \"offset\": 0,\n \"include_evidence_text\": true,\n \"evidence_text_mode\": \"full\",\n \"evidence_posts_limit\": 5,\n \"filters\": {\n \"job_titles\": {\n \"include\": [\"Head of Growth\"],\n \"exclude\": [],\n \"mode\": \"must\",\n \"exact\": false,\n \"current_only\": true\n },\n \"locations\": {\n \"include\": [\"New York, NY\"],\n \"exclude\": [],\n \"radius_miles\": 25,\n \"strict\": false,\n \"scope\": \"current\"\n }\n }\n }'" }, { "title": "Social proximity detail", "category": "social-proximity", "description": "Inspect authenticated score breakdown, evidence, connector paths, and LinkedIn mutual research status for one target.", "request": null, "response": { "baseline": { "score": 58, "tier": "Warm", "tier_key": "warm", "band": "warm", "evidence": [ { "label": "Connected on LinkedIn", "category": "direct_relationship", "source": "linkedin" }, { "label": "Very high LinkedIn mutual overlap", "category": "mutual_connections", "source": "linkedin" } ] }, "researched": { "score": 63, "tier": "Warm", "tier_key": "warm", "band": "warm", "evidence": [ { "label": "Connected on LinkedIn", "category": "direct_relationship", "source": "linkedin" }, { "label": "Very high LinkedIn mutual overlap", "category": "mutual_connections", "source": "linkedin" }, { "label": "Many shared SuperCarl mutuals", "category": "mutual_connections", "source": "supercarl" } ] }, "evidence": [ { "label": "Connected on LinkedIn", "category": "direct_relationship", "source": "linkedin" }, { "label": "Very high LinkedIn mutual overlap", "category": "mutual_connections", "source": "linkedin" } ], "connectors_supercarl": [ { "id": "user_456", "name": "Mutual Connector", "connector_type": "supercarl", "action_mode": "supercarl_referral", "path_score": 67.2, "social_proximity_score": 61, "social_proximity_band": "warm", "social_proximity_tier": "Warm", "viewer_social_proximity_score": 61, "target_social_proximity_score": 76, "evidence_highlights": [ "Super Carl Connector" ], "intersection_highlights": [ "Very high LinkedIn mutual overlap" ] } ], "connectors_linkedin_manual": [], "research_status": { "status": "completed", "current_start_index": 0, "page_size": 10, "pages_fetched": 3, "profiles_discovered": 17, "has_more": false, "exhausted": true, "next_page_number": 4, "browser_job_id": null, "reasoning_context_type": "social_proximity_research", "reasoning_context_id": "user_123", "updated_at": "2026-03-17T12:00:00.000Z", "last_error": null, "failure_reason": null, "recovery_action": null, "requires_linkedin_session": false, "message": "LinkedIn mutual research is up to date." }, "score_version": 7 }, "curl": "curl -X GET https://api.supercarl.ai/users//social-proximity \\\n -H \"Authorization: Bearer \"" }, { "title": "Preview search", "category": "people-search", "description": "Run a lightweight preview search (auto-translated description, not enrichable).", "request": { "description": "VP of Sales", "limit": 5, "offset": 0 }, "response": { "success": true, "search_id": null, "enrichable": false, "users": [], "pagination": { "limit": 5, "offset": 0, "total": 40, "hasMore": true } } }, { "title": "Enrich search results", "category": "people-search", "description": "Re-run a previous search_id and enrich the current page of results. Add target_user_id if you only want one user.", "request": { "search_id": "8c7fbf1a-5db5-4b15-9c76-6f4b3be3f7f4", "limit": 10, "offset": 0 }, "response": { "success": true, "search_id": "8c7fbf1a-5db5-4b15-9c76-6f4b3be3f7f4", "enrichment": { "duration_ms": 842, "mode": "page", "target_user_id": null }, "users": [ { "id": "user_123", "name": "Sample Person", "match_reasons": [ "Matched title: Head of Growth", "Location: New York" ] } ] } }, { "title": "Company search preview", "category": "companies", "description": "Search companies in detailed mode with inline evidence_text for downstream ranking or eval workflows.", "request": { "query": "AI infrastructure companies in California with 200+ employees hiring SREs", "result_mode": "detailed", "include_evidence_text": true, "evidence_post_limit": 2, "filters": { "company_headcount": { "min": "200", "max": null }, "funding": { "min_amount": "5M", "max_amount": null }, "revenue": { "min": "25M", "max": "1B" } }, "preview_limit": 10 }, "response": { "success": true, "companies": [ { "id": "company_123", "name": "Example GPU Systems", "canonical_name": "Example GPU Systems", "website_url": "https://examplegpu.com", "linkedin_company_url": "https://www.linkedin.com/company/examplegpu", "industries": [ "AI Infrastructure" ], "company_tags": [ "MLOps", "Cloud" ], "location": "San Francisco, CA", "employee_count": 320, "active_job_postings_count": 12, "match_evidence": { "matching_job_titles": [ "Site Reliability Engineer", "Platform Engineer" ] }, "evidence_text": "Company: Example GPU Systems\nDescription: Builds AI infrastructure for enterprise workloads.\nTechnologies: CUDA, Kubernetes\nRecent posts:\nPost 1 | 2026-03-01: Hiring SREs to scale GPU clusters." } ], "pagination": { "limit": 10, "offset": 0, "total": 42, "hasMore": true }, "filters": { "location": { "country": "United States", "state": "California" }, "company_headcount": { "min": 200, "max": null }, "job_keyword_hints": [ "SRE" ] }, "annotationPayload": { "preview": { "search_id": "company_search_abc", "total_count": 42 } }, "company_resolution": { "intent": "company_set", "status": "set", "can_bind_people_search": true, "recommended_next_action": "use_search_id_as_company_set" } } }, { "title": "People search joined to company search", "category": "companies", "description": "Use a company search_id as a people-search filter (include or exclude).", "request": { "description": "Find engineering leaders at those companies", "filters": { "companies": { "include_company_search_id": "company_search_abc" } } }, "response": { "success": true, "search_id": "people_search_xyz", "users": [], "pagination": { "limit": 20, "offset": 0, "total": 120, "hasMore": true }, "search_metadata": { "company_search_filters": { "include": { "search_id": "company_search_abc", "applied": true, "capped": false, "dropped": false, "total": 4200, "limit": 10000 } } } } }, { "title": "Profile snapshot", "category": "profiles", "description": "Fetch a profile snapshot by user id.", "request": null, "response": { "id": "user_123", "name": "Sample Person", "username": "sampleperson", "bio": "Growth leader.", "location": "New York, NY", "linkedin_url": "https://linkedin.com/in/example" } } ] }