Merge remote-tracking branch 'upstream/dev' into fix/onboarding

This commit is contained in:
Anish Sarkar 2026-07-14 10:18:03 +05:30
commit 2d837ea18c
185 changed files with 4729 additions and 3630 deletions

View file

@ -3,7 +3,6 @@
import { Check, Copy, Download } from "lucide-react";
import { useMemo, useState } from "react";
import { Button } from "@/components/ui/button";
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
import {
Table,
TableBody,
@ -12,6 +11,7 @@ import {
TableHeader,
TableRow,
} from "@/components/ui/table";
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
import { downloadCsv, rowsToCsv } from "@/lib/playground/csv";
const MAX_TABLE_ROWS = 200;
@ -117,13 +117,7 @@ export function OutputViewer({ data, filenameBase }: { data: unknown; filenameBa
</Tabs>
<div className="flex items-center gap-1">
{items && items.length > 0 && (
<Button
type="button"
variant="ghost"
size="sm"
onClick={exportCsv}
className="gap-1.5"
>
<Button type="button" variant="ghost" size="sm" onClick={exportCsv} className="gap-1.5">
<Download className="h-3.5 w-3.5" />
Export CSV
</Button>

View file

@ -25,7 +25,8 @@ export function PlaygroundIndex({ workspaceId }: { workspaceId: number }) {
<Info />
<AlertDescription>
<p>
Manually run SurfSense's platform-native APIs and inspect their output. To use these APIs outside SurfSense,{" "}
Manually run SurfSense's platform-native APIs and inspect their output. To use these
APIs outside SurfSense,{" "}
<Link
href={`${base}/api-keys`}
className="font-medium text-foreground underline-offset-4 hover:underline"

View file

@ -35,13 +35,7 @@ function parseJsonl(text: string | null): { items: unknown[]; total: number } {
return { items, total: lines.length };
}
export function RunDetail({
workspaceId,
runId,
}: {
workspaceId: number;
runId: string;
}) {
export function RunDetail({ workspaceId, runId }: { workspaceId: number; runId: string }) {
const { data: run, isLoading, error } = useScraperRun(workspaceId, runId);
const parsed = useMemo(() => parseJsonl(run?.output_text ?? null), [run?.output_text]);

View file

@ -9,7 +9,9 @@ import { formatDuration } from "@/lib/playground/format";
function eventLabel(event: ScraperRunEvent): string {
const base =
event.message ||
(event.phase ? event.phase.replace(/_/g, " ").replace(/^\w/, (c) => c.toUpperCase()) : "Working");
(event.phase
? event.phase.replace(/_/g, " ").replace(/^\w/, (c) => c.toUpperCase())
: "Working");
if (event.current !== undefined && event.current !== null) {
const counter =
event.total !== undefined && event.total !== null

View file

@ -14,7 +14,10 @@ export function RunStatusBadge({ status }: { status: string }) {
}
if (normalized === "success") {
return (
<Badge variant="secondary" className="bg-emerald-500/15 text-emerald-600 dark:text-emerald-400">
<Badge
variant="secondary"
className="bg-emerald-500/15 text-emerald-600 dark:text-emerald-400"
>
Success
</Badge>
);

View file

@ -71,7 +71,8 @@ export function RunsTable({ workspaceId }: { workspaceId: number }) {
<Alert>
<Info />
<AlertDescription>
View all API runs for this workspace, including runs from the playground, API keys, and agents.
View all API runs for this workspace, including runs from the playground, API keys, and
agents.
</AlertDescription>
</Alert>

View file

@ -43,12 +43,7 @@ function FieldControl({
if (field.kind === "boolean") {
return (
<Switch
id={id}
checked={Boolean(value)}
onCheckedChange={onChange}
disabled={disabled}
/>
<Switch id={id} checked={Boolean(value)} onCheckedChange={onChange} disabled={disabled} />
);
}
@ -141,9 +136,7 @@ function FieldRow({
{field.required ? "required" : "optional"}
</Badge>
</div>
{field.description && (
<p className="text-xs text-muted-foreground">{field.description}</p>
)}
{field.description && <p className="text-xs text-muted-foreground">{field.description}</p>}
<FieldControl
field={field}
value={value}
@ -156,13 +149,7 @@ function FieldRow({
);
}
export function SchemaForm({
fields,
values,
onChange,
disabled,
fieldErrors,
}: SchemaFormProps) {
export function SchemaForm({ fields, values, onChange, disabled, fieldErrors }: SchemaFormProps) {
const [showAdvanced, setShowAdvanced] = useState(false);
const { primary, advanced } = useMemo(() => {

View file

@ -0,0 +1,5 @@
import { AppearanceContent } from "../components/AppearanceContent";
export default function Page() {
return <AppearanceContent />;
}

View file

@ -0,0 +1,43 @@
"use client";
import { useAtom } from "jotai";
import { showMessageTimestampsAtom } from "@/atoms/chat/show-timestamps.atom";
import { Label } from "@/components/ui/label";
import { Switch } from "@/components/ui/switch";
export function AppearanceContent() {
const [showTimestamps, setShowTimestamps] = useAtom(showMessageTimestampsAtom);
return (
<div className="flex flex-col gap-4 md:gap-6">
<section>
<div className="pb-2 md:pb-3">
<h2 className="text-base md:text-lg font-semibold">Chat</h2>
<p className="text-xs md:text-sm text-muted-foreground">
Control how messages are displayed in your conversations.
</p>
</div>
<div className="flex flex-col gap-3">
<div className="flex items-center justify-between rounded-lg bg-accent p-4">
<div className="space-y-0.5">
<Label
htmlFor="show-timestamps-toggle"
className="text-sm font-medium cursor-pointer"
>
Show message timestamps
</Label>
<p className="text-xs text-muted-foreground">
Display the time under each message in a chat. Saved on this device.
</p>
</div>
<Switch
id="show-timestamps-toggle"
checked={showTimestamps}
onCheckedChange={setShowTimestamps}
/>
</div>
</div>
</section>
</div>
);
}

View file

@ -7,6 +7,7 @@ import {
Library,
MessageCircle,
Monitor,
Palette,
ReceiptText,
ShieldCheck,
WandSparkles,
@ -20,6 +21,7 @@ import { usePlatform } from "@/hooks/use-platform";
export type UserSettingsTab =
| "profile"
| "appearance"
| "api-key"
| "prompts"
| "community-prompts"
@ -49,6 +51,12 @@ export function UserSettingsLayoutShell({ workspaceId, children }: UserSettingsL
href: `/dashboard/${workspaceId}/user-settings/profile`,
icon: <CircleUser className="h-4 w-4" />,
},
{
value: "appearance" as const,
label: "Appearance",
href: `/dashboard/${workspaceId}/user-settings/appearance`,
icon: <Palette className="h-4 w-4" />,
},
{
value: "api-key" as const,
label: t("api_key_nav_label"),

View file

@ -50,7 +50,7 @@ export const metadata: Metadata = {
alternates: {
canonical: "https://www.surfsense.com",
},
title: "SurfSense - Competitive Intelligence Platform for AI Agents",
title: "SurfSense - NotebookLM for Competitive Intelligence",
description:
"SurfSense is an open-source competitive intelligence platform. Your AI agents monitor competitors, track rankings, and listen to your market through one API or MCP server.",
keywords: [
@ -68,7 +68,7 @@ export const metadata: Metadata = {
"SurfSense",
],
openGraph: {
title: "SurfSense - Competitive Intelligence Platform for AI Agents",
title: "SurfSense - NotebookLM for Competitive Intelligence",
description:
"SurfSense is an open-source competitive intelligence platform. Your AI agents monitor competitors, track rankings, and listen to your market through one API or MCP server.",
url: "https://www.surfsense.com",
@ -86,7 +86,7 @@ export const metadata: Metadata = {
},
twitter: {
card: "summary_large_image",
title: "SurfSense - Competitive Intelligence Platform for AI Agents",
title: "SurfSense - NotebookLM for Competitive Intelligence",
description:
"SurfSense is an open-source competitive intelligence platform. Your AI agents monitor competitors, track rankings, and listen to your market through one API or MCP server.",
creator: "@SurfSenseAI",

View file

@ -0,0 +1,11 @@
import { atomWithStorage } from "jotai/utils";
/**
* Per-device preference: show a timestamp under each chat message.
*
* Off by default to match streaming-AI chat convention (ChatGPT/Claude keep
* the message stream clean and put time in the conversation list). Persisted
* in localStorage, so it does not sync across devices acceptable for a
* cosmetic display toggle.
*/
export const showMessageTimestampsAtom = atomWithStorage<boolean>("chat-show-timestamps:v1", false);

View file

@ -35,6 +35,7 @@ import {
useAllCitationMetadata,
} from "@/components/assistant-ui/citation-metadata-context";
import { MarkdownText } from "@/components/assistant-ui/markdown-text";
import { MessageTimestamp } from "@/components/assistant-ui/message-timestamp";
import { ReasoningMessagePart } from "@/components/assistant-ui/reasoning-message-part";
import { RevertTurnButton } from "@/components/assistant-ui/revert-turn-button";
import {
@ -62,6 +63,7 @@ import { withArtifactAnchor } from "@/features/chat-artifacts";
import { useComments } from "@/hooks/use-comments";
import { useMediaQuery } from "@/hooks/use-media-query";
import { useElectronAPI } from "@/hooks/use-platform";
import { formatMessageTimestamp } from "@/lib/format-date";
import { getProviderIcon } from "@/lib/provider-icons";
import { tryGetHostname } from "@/lib/url";
import { cn } from "@/lib/utils";
@ -249,16 +251,6 @@ export const MessageError: FC = () => {
);
};
function formatMessageDate(date: Date): string {
return date.toLocaleDateString(undefined, {
month: "short",
day: "numeric",
hour: "numeric",
minute: "2-digit",
hour12: true,
});
}
/**
* Format provider USD cost (in micro-USD) for inline display next to a
* token count. Falls back to ``"<$0.001"`` for sub-tenth-of-a-cent
@ -367,7 +359,7 @@ const MessageInfoDropdown: FC<{ chatTurnId: string | null | undefined }> = ({ ch
>
{createdAt && (
<DropdownMenuLabel className="text-xs text-muted-foreground font-normal select-none">
{formatMessageDate(createdAt)}
{formatMessageTimestamp(createdAt)}
</DropdownMenuLabel>
)}
{hasUsage && (
@ -463,6 +455,8 @@ const AssistantMessageInner: FC = () => {
<MessageError />
</div>
<MessageTimestamp className="ml-2 mt-2" />
{isMobile && (
<div className="ml-2 mt-2">
<MobileCitationDrawer />

View file

@ -0,0 +1,24 @@
import { useAuiState } from "@assistant-ui/react";
import { useAtomValue } from "jotai";
import type { FC } from "react";
import { showMessageTimestampsAtom } from "@/atoms/chat/show-timestamps.atom";
import { formatMessageTimestamp } from "@/lib/format-date";
import { cn } from "@/lib/utils";
/**
* Muted, always-visible timestamp under a chat message. Renders only when the
* user has opted in via {@link showMessageTimestampsAtom} and the message
* carries a ``createdAt`` (absent on optimistic pre-persist messages).
*/
export const MessageTimestamp: FC<{ className?: string }> = ({ className }) => {
const show = useAtomValue(showMessageTimestampsAtom);
const createdAt = useAuiState(({ message }) => message?.createdAt);
if (!show || !createdAt) return null;
return (
<div className={cn("select-none text-[11px] text-muted-foreground", className)}>
{formatMessageTimestamp(createdAt)}
</div>
);
};

View file

@ -1070,10 +1070,7 @@ const ConnectedScraperIcons: FC<{ workspaceId: number }> = ({ workspaceId }) =>
return (
<Tooltip key={platform.id}>
<TooltipTrigger asChild>
<Avatar
className="size-5"
style={{ zIndex: platforms.length - i }}
>
<Avatar className="size-5" style={{ zIndex: platforms.length - i }}>
<AvatarFallback className="bg-popover text-[10px]">
<Icon className="size-3" />
</AvatarFallback>

View file

@ -22,6 +22,7 @@ import { currentThreadAtom } from "@/atoms/chat/current-thread.atom";
import { messageDocumentsMapAtom } from "@/atoms/chat/mentioned-documents.atom";
import { openEditorPanelAtom } from "@/atoms/editor/editor-panel.atom";
import { MentionChip } from "@/components/assistant-ui/mention-chip";
import { MessageTimestamp } from "@/components/assistant-ui/message-timestamp";
import { TooltipIconButton } from "@/components/assistant-ui/tooltip-icon-button";
import { getConnectorIcon } from "@/contracts/enums/connectorIcons";
import { getMentionDocKey } from "@/lib/chat/mention-doc-key";
@ -182,6 +183,7 @@ export const UserMessage: FC = () => {
</div>
)}
</div>
<MessageTimestamp className="mt-1 pl-1" />
</div>
</MessagePrimitive.Root>
);

View file

@ -0,0 +1,23 @@
"use client";
import { useEffect } from "react";
import { chatStreamStore } from "@/lib/chat/stream-engine/store";
/**
* Persistent, render-null host that scopes the in-flight chat turn's lifetime
* to the workspace shell, not the chat page.
*
* Mounted in ``LayoutDataProvider``, it survives in-app navigation between
* workspace routes and aborts the single active turn only on workspace/app
* teardown, so ordinary navigation disconnects the view without stopping the
* stream.
*/
export function ActiveChatStreamRunner() {
useEffect(() => {
return () => {
chatStreamStore.abortActive();
};
}, []);
return null;
}

View file

@ -27,7 +27,8 @@ export type HeroChatDemoScript = {
type Stage = "typing" | "steps" | "answer" | "done";
const PLACEHOLDER = "Track competitors, scrape platforms, automate briefs. Use / for prompts, @ for docs";
const PLACEHOLDER =
"Track competitors, scrape platforms, automate briefs. Use / for prompts, @ for docs";
/** Blinking caret for the typewriter (overlay only, never inside the real input). */
function Caret() {

View file

@ -708,7 +708,7 @@ export function HeroSection() {
"relative mt-4 max-w-4xl text-left text-4xl font-bold tracking-tight text-balance text-neutral-900 sm:text-5xl md:text-6xl dark:text-neutral-50"
)}
>
<Balancer>Give your AI agents competitive intelligence.</Balancer>
<Balancer>NotebookLM for competitive intelligence research.</Balancer>
</h1>
<div className="mt-4 flex w-full flex-col items-start justify-between gap-4 md:mt-8 md:flex-row md:items-end md:gap-10">
<div>
@ -717,9 +717,10 @@ export function HeroSection() {
"relative mb-8 max-w-2xl text-left text-sm text-neutral-600 antialiased sm:text-base md:text-lg dark:text-neutral-400"
)}
>
SurfSense is an open-source competitive intelligence platform. Your AI agents monitor
competitors, track rankings, and listen to your market with live data from platforms
like Reddit, YouTube, Instagram, TikTok, Google Maps, Google Search, and the open web.
SurfSense is an open-source competitive intelligence platform, like NotebookLM but
with live scraping connectors. Your AI agents monitor competitors, track rankings, and
listen to your market with live data from platforms like Reddit, YouTube, Instagram,
TikTok, Google Maps, Google Search, and the open web.
</p>
<div className="relative mb-4 flex w-full flex-col justify-center gap-y-2 sm:flex-row sm:justify-start sm:space-y-0 sm:space-x-4">

View file

@ -27,6 +27,7 @@ export { default as PerplexityIcon } from "./perplexity.svg";
export { default as QwenIcon } from "./qwen.svg";
export { default as RecraftIcon } from "./recraft.svg";
export { default as ReplicateIcon } from "./replicate.svg";
export { default as RequestyIcon } from "./requesty.svg";
export { default as SambaNovaIcon } from "./sambanova.svg";
export { default as TogetherAiIcon } from "./togetherai.svg";
export { default as VertexAiIcon } from "./vertexai.svg";

View file

@ -0,0 +1 @@
<svg fill="currentColor" fill-rule="evenodd" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 2a1 1 0 000 2h2.086l-5.293 5.293a1 1 0 001.414 1.414L18 5.414V7.5a1 1 0 102 0v-4.5a1 1 0 00-1-1h-4.5zM4 6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4a1 1 0 10-2 0v4H4V8h4a1 1 0 000-2H4z"></path></svg>

After

Width:  |  Height:  |  Size: 318 B

View file

@ -18,6 +18,7 @@ import { workspacesAtom } from "@/atoms/workspaces/workspace-query.atoms";
import { ActionLogDialog } from "@/components/agent-action-log/action-log-dialog";
import { AnnouncementSpotlight } from "@/components/announcements/AnnouncementSpotlight";
import { AnnouncementsDialog } from "@/components/announcements/AnnouncementsDialog";
import { ActiveChatStreamRunner } from "@/components/chat/active-chat-stream-runner";
import {
AlertDialog,
AlertDialogAction,
@ -649,6 +650,9 @@ export function LayoutDataProvider({
return (
<>
{/* Persistent host: keeps an in-flight chat turn streaming across
in-app navigation and aborts it only on workspace teardown. */}
<ActiveChatStreamRunner />
<LayoutShell
workspaces={workspaces}
activeWorkspaceId={Number(workspaceId)}

View file

@ -324,9 +324,7 @@ export function NotificationsDropdown({
)}
>
<span>{tab.label}</span>
<span
className="inline-flex h-5 min-w-5 items-center justify-center rounded-full bg-muted px-1.5 text-[11px] font-semibold text-muted-foreground"
>
<span className="inline-flex h-5 min-w-5 items-center justify-center rounded-full bg-muted px-1.5 text-[11px] font-semibold text-muted-foreground">
{formatNotificationCount(tab.count)}
</span>
</button>

View file

@ -198,8 +198,8 @@ export function AutoReloadSettings() {
<AlertTriangle className="h-4 w-4" />
<AlertTitle>Last top-up failed</AlertTitle>
<AlertDescription>
Your saved card was declined and top-ups were turned off. Update your card and
re-enable top-ups below.
Your saved card was declined and top-ups were turned off. Update your card and re-enable
top-ups below.
</AlertDescription>
</Alert>
)}
@ -290,7 +290,11 @@ export function AutoReloadSettings() {
</div>
<div className="flex justify-end">
<Button className="w-full sm:w-auto" onClick={handleSave} disabled={saveMutation.isPending}>
<Button
className="w-full sm:w-auto"
onClick={handleSave}
disabled={saveMutation.isPending}
>
{saveMutation.isPending ? (
<>
<Spinner size="xs" />

View file

@ -9,9 +9,17 @@ function baseUrlHint(provider: string) {
return "For local servers, use host.docker.internal instead of localhost.";
}
if (provider === "openai_compatible") {
return "Enter the full endpoint URL.";
return "Enter the full endpoint URL. This provider expects a /v1-compatible endpoint.";
}
if (provider === "openai" || provider === "anthropic" || provider === "openrouter") {
if (provider === "openai_compatible_raw") {
return "Enter the exact chat-completions API base URL. SurfSense will not append /v1.";
}
if (
provider === "openai" ||
provider === "anthropic" ||
provider === "openrouter" ||
provider === "requesty"
) {
return "Override only if you route through a proxy or gateway.";
}
return undefined;

View file

@ -7,9 +7,11 @@ export const PROVIDER_ORDER = [
"bedrock",
"azure",
"openrouter",
"requesty",
"ollama_chat",
"lm_studio",
"openai_compatible",
"openai_compatible_raw",
];
export const PROVIDER_DISPLAY: Record<
@ -37,12 +39,23 @@ export const PROVIDER_DISPLAY: Record<
subtitle: "OpenAI-compatible endpoint",
iconKey: "custom",
},
openai_compatible_raw: {
name: "OpenAI-Compatible Raw",
subtitle: "Use the exact base URL, no /v1 is appended",
iconKey: "custom",
},
openrouter: {
name: "OpenRouter",
subtitle: "OpenRouter",
iconKey: "openrouter",
defaultBaseUrl: "https://openrouter.ai/api/v1",
},
requesty: {
name: "Requesty",
subtitle: "Requesty",
iconKey: "requesty",
defaultBaseUrl: "https://router.requesty.ai/v1",
},
vertex_ai: { name: "Gemini", subtitle: "Google Cloud Vertex AI", iconKey: "vertex_ai" },
};

View file

@ -59,7 +59,12 @@ export function WorkspaceApiAccessControl({
if (isLoading) {
return (
<div className={cn("flex flex-col gap-3 md:flex-row md:items-center md:justify-between", className)}>
<div
className={cn(
"flex flex-col gap-3 md:flex-row md:items-center md:justify-between",
className
)}
>
<div className="space-y-2">
<Skeleton className="h-4 w-32" />
<Skeleton className="h-3 w-56" />
@ -71,7 +76,12 @@ export function WorkspaceApiAccessControl({
if (isError) {
return (
<div className={cn("flex flex-col gap-3 md:flex-row md:items-center md:justify-between", className)}>
<div
className={cn(
"flex flex-col gap-3 md:flex-row md:items-center md:justify-between",
className
)}
>
<div className="space-y-1">
<Label>API key access</Label>
<p className="text-xs text-destructive">Failed to load workspace API access.</p>
@ -84,7 +94,12 @@ export function WorkspaceApiAccessControl({
}
return (
<div className={cn("flex flex-col gap-3 md:flex-row md:items-center md:justify-between", className)}>
<div
className={cn(
"flex flex-col gap-3 md:flex-row md:items-center md:justify-between",
className
)}
>
<div className="space-y-1">
<Label htmlFor="api-access-enabled">API key access</Label>
<p className="text-xs text-muted-foreground">Allow API keys to access this workspace.</p>

View file

@ -1,5 +1,13 @@
{
"title": "Native Connectors",
"pages": ["reddit", "youtube", "instagram", "tiktok", "google-maps", "google-search", "web-crawl"],
"pages": [
"reddit",
"youtube",
"instagram",
"tiktok",
"google-maps",
"google-search",
"web-crawl"
],
"defaultOpen": false
}

View file

@ -11,15 +11,14 @@ The TikTok connector pulls structured public data from TikTok across four verbs:
POST /api/v1/workspaces/{workspace_id}/scrapers/tiktok/scrape
```
Give it URLs (a video, a profile, a hashtag, or a search page) and/or profiles, hashtags, or search terms; returns videos (caption, author, play/like/comment/share counts, music, hashtags, timestamps, and the web URL). At least one of `urls`, `profiles`, `hashtags`, or `search_queries` is required.
Give it URLs (a video, a profile, a hashtag, or a search page) and/or profiles or hashtags; returns videos (caption, author, play/like/comment/share counts, music, hashtags, timestamps, and the web URL). At least one of `urls`, `profiles`, or `hashtags` is required.
| Field | Default | Description |
|-------|---------|-------------|
| `urls` | — | TikTok URLs: a video, a profile (`/@<user>`), a hashtag (`/tag/<name>`), or a search URL (max 20 sources per call) |
| `profiles` | — | Profile usernames, with or without a leading `@` |
| `hashtags` | — | Hashtag names, without the `#` |
| `search_queries` | — | Search terms to run on TikTok |
| `results_per_page` | `10` | Max videos per profile/hashtag/search target |
| `results_per_page` | `10` | Max videos per profile/hashtag target |
| `max_items` | `10` | Max total videos returned across all sources (hard cap 100) |
```bash
@ -30,7 +29,7 @@ curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/tiktok/scrape" \
```
<Callout type="info">
Video and hashtag targets are the reliable video paths. A `profiles` target returns the account's **metadata** (name, followers, bio, verification) reliably, but TikTok often withholds its **video list** from automated clients — so a profile can return metadata with no videos. Keyword **video** search is login-walled and returns a surfaced error; to find accounts by keyword use **user search** below.
Video and hashtag targets are the reliable video paths. A `profiles` target returns the account's **metadata** (name, followers, bio, verification) reliably, but TikTok often withholds its **video list** from automated clients — so a profile can return metadata with no videos. There is no keyword **video** search (TikTok's own search is login-walled); to find accounts by keyword use **user search** below.
</Callout>
## Comments

View file

@ -143,14 +143,48 @@ To update SurfSense, see [Updating](/docs/docker-installation/updating).
## Building from Source (Contributors)
If you're contributing to SurfSense and want to build the images from your local checkout, use the dev compose file:
If you're contributing to SurfSense and want to build the images from your local checkout, use the dev compose file. Unlike the production setup above, there's no bundled Caddy proxy — each service publishes its own port directly, and you need **three** separate `.env` files instead of one.
**Requirements:** Docker with the `buildx` plugin (needed for the multi-stage `Dockerfile`; a plain `docker build` without BuildKit fails). Check with `docker buildx version` — if missing, install `docker-buildx` (or `docker-buildx-plugin` on some distros).
```bash
cd SurfSense/docker
git clone https://github.com/<your-fork>/SurfSense.git
cd SurfSense
cp docker/.env.example docker/.env
cp surfsense_backend/.env.example surfsense_backend/.env
cp surfsense_web/.env.example surfsense_web/.env
```
`docker/.env` only configures Docker Compose variable substitution — it is **not** passed into the containers. The backend and frontend read their own `.env` files instead (wired via `env_file:` in `docker-compose.dev.yml`).
Edit before starting:
- **`SECRET_KEY`** in `surfsense_backend/.env` — required, generate with `openssl rand -base64 32`. Note this is separate from `SECRET_KEY` in `docker/.env`; the dev compose file does not forward one to the other.
Everything else in the three example files (auth type, Stripe, connector OAuth credentials, messaging bots, proxy settings, etc.) is optional — only needed if you're testing that specific integration.
```bash
cd docker
docker compose -f docker-compose.dev.yml up --build
```
It builds the backend and frontend from source, publishes raw service ports for debugging, and includes pgAdmin at [http://localhost:5050](http://localhost:5050). There's also a `docker-compose.deps-only.yml` that runs just the dependencies (Postgres, Redis, zero-cache) in Docker while you run the backend and frontend natively — see [Manual Installation](/docs/manual-installation#alternative-let-docker-manage-all-dependencies).
| Service | Port | Notes |
|---------|------|-------|
| `frontend` | `localhost:3000` | Next.js dev server |
| `backend` | `localhost:8000` | FastAPI, `/ready` for healthcheck |
| `pgadmin` | `localhost:5050` | Postgres GUI |
| `zero-cache` | `localhost:4848` (ws) | Real-time sync |
| `celery_worker` | — | Background task processing, no exposed port |
| `celery_beat` | — | Periodic task scheduler, no exposed port |
| `otel-lgtm` | `localhost:3001` | Grafana + Loki + Tempo + Mimir bundle, for tracing/metrics |
Observability (`otel-lgtm`) isn't needed for regular dev work — it's the heaviest non-essential service, so skip it if you're not debugging traces/metrics:
```bash
docker compose -f docker-compose.dev.yml up --build db redis zero-cache backend celery_worker celery_beat frontend
```
There's also a `docker-compose.deps-only.yml` that runs just the dependencies (Postgres, Redis, zero-cache) in Docker while you run the backend and frontend natively — see [Manual Installation](/docs/manual-installation#alternative-let-docker-manage-all-dependencies).
## Troubleshooting

View file

@ -89,17 +89,12 @@ export function useRunStream(workspaceId: number) {
setState((s) => ({
...s,
latest: ev,
events:
ev.type === "run.progress"
? [...s.events.slice(-(MAX_LOG - 1)), ev]
: s.events,
events: ev.type === "run.progress" ? [...s.events.slice(-(MAX_LOG - 1)), ev] : s.events,
}));
}
} catch (e) {
if (signal.aborted) return;
setState((s) =>
s.status === "running" ? { ...s, status: "error", error: e } : s
);
setState((s) => (s.status === "running" ? { ...s, status: "error", error: e } : s));
}
},
[workspaceId, queryClient]
@ -113,12 +108,7 @@ export function useRunStream(workspaceId: number) {
startedAtRef.current = Date.now();
setState({ ...INITIAL, status: "running" });
try {
const started = await scrapersApiService.runAsync(
workspaceId,
platform,
verb,
payload
);
const started = await scrapersApiService.runAsync(workspaceId, platform, verb, payload);
runIdRef.current = started.run_id;
trackWeeklyUser("api_run", workspaceId);
setState((s) => ({ ...s, runId: started.run_id }));

View file

@ -1,15 +1,15 @@
import {
type ListScraperRunsParams,
type ScraperRunEvent,
type StartAsyncRunResponse,
listCapabilitiesResponse,
listRunsResponse,
type ScraperRunEvent,
type StartAsyncRunResponse,
scraperRunDetail,
startAsyncRunResponse,
} from "@/contracts/types/scraper.types";
import { authenticatedFetch } from "@/lib/auth-fetch";
import { readSSEStream } from "@/lib/chat/streaming-state";
import { buildBackendUrl } from "@/lib/env-config";
import { authenticatedFetch } from "@/lib/auth-fetch";
import { baseApiService } from "./base-api.service";
const base = (workspaceId: number | string) => `/api/v1/workspaces/${workspaceId}/scrapers`;

View file

@ -40,6 +40,7 @@ const PUBLIC_ROUTE_PREFIXES = [
"/external-mcp-connectors",
"/reddit",
"/instagram",
"/tiktok",
"/youtube",
"/google-maps",
"/google-search",

File diff suppressed because it is too large Load diff

View file

@ -0,0 +1,154 @@
import { z } from "zod";
import type { MentionedDocumentInfo } from "@/atoms/chat/mentioned-documents.atom";
import type { ToolUIGate } from "@/lib/chat/streaming-state";
/**
* Every tool call renders a card. The sentinel ``"all"`` matches every tool
* the legacy ``BASE_TOOLS_WITH_UI`` allowlist was dropped so unknown tool
* calls route through the generic ``ToolFallback``. Persisted payload size
* stays bounded because the backend's ``format_thinking_step`` summarisation
* and the ``result_length``-only default for unknown tools keep the JSON
* from ballooning.
*/
export const TOOLS_WITH_UI_ALL: ToolUIGate = "all";
export const TURN_CANCELLING_INITIAL_DELAY_MS = 200;
export const TURN_CANCELLING_BACKOFF_FACTOR = 2;
export const TURN_CANCELLING_MAX_DELAY_MS = 1500;
export const RECENT_CANCEL_WINDOW_MS = 5_000;
export function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
export function computeFallbackTurnCancellingRetryDelay(attempt: number): number {
const safeAttempt = Math.max(1, attempt);
const raw =
TURN_CANCELLING_INITIAL_DELAY_MS * TURN_CANCELLING_BACKOFF_FACTOR ** (safeAttempt - 1);
return Math.min(raw, TURN_CANCELLING_MAX_DELAY_MS);
}
/**
* Generate a synthetic ``toolCallId`` for an action_request that has no
* matching streamed tool-call card (HITL-blocked subagent calls don't surface
* as tool-call events). Suffixes a counter when the base id is already taken
* sequential interrupts for the same tool name otherwise collide on
* ``interrupt-${name}-${i}`` and crash assistant-ui with a duplicate-key error.
*/
export function freshSynthToolCallId(
toolCallIndices: Map<string, number>,
toolName: string,
index: number
): string {
const base = `interrupt-${toolName}-${index}`;
if (!toolCallIndices.has(base)) return base;
let n = 1;
while (toolCallIndices.has(`${base}-${n}`)) n++;
return `${base}-${n}`;
}
/**
* Pair each ``action_request`` to a unique pending tool-call card, preserving
* order so ``decisions[i]`` lines up with ``action_requests[i]`` on the wire.
*
* Same-name bundles (e.g. three ``create_jira_issue``) used to collapse onto
* one card because the matcher keyed by name; this consumes each card via the
* ``claimed`` set and walks forward in DOM order.
*/
export function pairBundleToolCallIds(
toolCallIndices: Map<string, number>,
contentParts: Array<{
type: string;
toolName?: string;
result?: unknown;
}>,
actionRequests: ReadonlyArray<{ name: string }>
): Array<string | null> {
const claimed = new Set<string>();
const paired: Array<string | null> = [];
for (const action of actionRequests) {
let matched: string | null = null;
for (const [tcId, idx] of toolCallIndices) {
if (claimed.has(tcId)) continue;
const part = contentParts[idx];
if (!part || part.type !== "tool-call" || part.toolName !== action.name) continue;
const result = part.result as Record<string, unknown> | undefined | null;
if (result == null || (result.__interrupt__ === true && !result.__decided__)) {
matched = tcId;
claimed.add(tcId);
break;
}
}
paired.push(matched);
}
return paired;
}
/**
* Zod schema for mentioned document info (for type-safe parsing).
*
* ``kind`` defaults to ``"doc"`` so messages persisted before folder
* mentions existed deserialise unchanged.
*/
const MentionedDocumentInfoSchema = z.object({
id: z.number(),
title: z.string(),
document_type: z.string().optional(),
kind: z
.union([z.literal("doc"), z.literal("folder"), z.literal("connector"), z.literal("thread")])
.optional()
.default("doc"),
connector_type: z.string().optional(),
account_name: z.string().optional(),
});
const MentionedDocumentsPartSchema = z.object({
type: z.literal("mentioned-documents"),
documents: z.array(MentionedDocumentInfoSchema),
});
/**
* Extract mentioned documents from message content (type-safe with Zod).
*/
export function extractMentionedDocuments(content: unknown): MentionedDocumentInfo[] {
if (!Array.isArray(content)) return [];
for (const part of content) {
const result = MentionedDocumentsPartSchema.safeParse(part);
if (result.success) {
return result.data.documents.map<MentionedDocumentInfo>((doc) => {
if (doc.kind === "connector") {
return {
id: doc.id,
title: doc.title,
kind: "connector",
connector_type: doc.connector_type ?? doc.document_type ?? "UNKNOWN",
account_name: doc.account_name ?? doc.title,
};
}
if (doc.kind === "folder") {
return {
id: doc.id,
title: doc.title,
kind: "folder",
};
}
if (doc.kind === "thread") {
return {
id: doc.id,
title: doc.title,
kind: "thread",
};
}
return {
id: doc.id,
title: doc.title,
document_type: doc.document_type ?? "UNKNOWN",
kind: "doc",
};
});
}
}
return [];
}

View file

@ -0,0 +1,177 @@
import type { ThreadMessageLike } from "@assistant-ui/react";
import { createTokenUsageStore } from "@/components/assistant-ui/token-usage-context";
import type { PendingInterruptState } from "@/features/chat-messages/hitl";
/**
* Durable, per-thread streaming state for a single in-flight chat turn.
*
* Lives at module scope (see {@link chatStreamStore}) so a running turn's
* messages / interrupts survive the chat page unmounting during in-app
* navigation. The React tree consumes it through ``useChatStream`` via
* ``useSyncExternalStore`` (state lives outside the render cycle).
*/
export interface ThreadStreamState {
threadId: number;
messages: ThreadMessageLike[];
isRunning: boolean;
pendingInterrupts: PendingInterruptState[];
}
type Listener = () => void;
/**
* Module-level singleton external store for chat streaming.
*
* Single-active-stream invariant: at most one turn streams at a time,
* tracked by {@link active}. Per-thread state is still keyed by threadId so
* the currently-streaming thread and the currently-viewed thread can differ
* (e.g. a stream finishes while the user is on another chat).
*
* ponytail: unbounded ``states`` map is bounded in practice by
* ``clearInactive`` (called on navigation) + ``clear`` (called after the DB
* re-hydrates a finished turn). Upgrade path if that ever leaks: LRU cap.
*/
class ChatStreamStore {
private states = new Map<number, ThreadStreamState>();
private listeners = new Set<Listener>();
/** Shared, cross-navigation token-usage store (one instance app-wide). */
readonly tokenUsage = createTokenUsageStore();
/** The one in-flight turn's abort handle, or null when idle. */
private active: { threadId: number; controller: AbortController } | null = null;
/** Timestamp of the last explicit cancel, for the THREAD_BUSY retry window. */
recentCancelRequestedAt = 0;
subscribe = (listener: Listener): (() => void) => {
this.listeners.add(listener);
return () => {
this.listeners.delete(listener);
};
};
private notify(): void {
for (const l of this.listeners) l();
}
/** Snapshot for ``useSyncExternalStore``; stable ref between mutations. */
getSnapshot = (threadId: number | null): ThreadStreamState | null => {
if (threadId == null) return null;
return this.states.get(threadId) ?? null;
};
isRunning(threadId: number | null): boolean {
if (threadId == null) return false;
return this.states.get(threadId)?.isRunning ?? false;
}
getMessages(threadId: number): ThreadMessageLike[] {
return this.states.get(threadId)?.messages ?? [];
}
getPendingInterrupts(threadId: number): PendingInterruptState[] {
return this.states.get(threadId)?.pendingInterrupts ?? [];
}
private ensure(threadId: number): ThreadStreamState {
let s = this.states.get(threadId);
if (!s) {
s = { threadId, messages: [], isRunning: false, pendingInterrupts: [] };
this.states.set(threadId, s);
}
return s;
}
private commit(threadId: number, next: ThreadStreamState): void {
this.states.set(threadId, next);
this.notify();
}
/** Seed a thread's state at the start of a fresh turn (running=true). */
begin(threadId: number, messages: ThreadMessageLike[]): void {
this.commit(threadId, { threadId, messages, isRunning: true, pendingInterrupts: [] });
}
setMessages(threadId: number, updater: (prev: ThreadMessageLike[]) => ThreadMessageLike[]): void {
const prev = this.ensure(threadId);
const messages = updater(prev.messages);
if (messages === prev.messages) return;
this.commit(threadId, { ...prev, messages });
}
setRunning(threadId: number, running: boolean): void {
const prev = this.ensure(threadId);
if (prev.isRunning === running) return;
this.commit(threadId, { ...prev, isRunning: running });
}
setPendingInterrupts(
threadId: number,
updater: (prev: PendingInterruptState[]) => PendingInterruptState[]
): void {
const prev = this.ensure(threadId);
const pendingInterrupts = updater(prev.pendingInterrupts);
if (pendingInterrupts === prev.pendingInterrupts) return;
this.commit(threadId, { ...prev, pendingInterrupts });
}
/**
* A thread whose overlay must survive DB re-hydration / navigation: it is
* either streaming or paused awaiting a HITL decision (the pending
* interrupts + interrupt cards live only in the overlay).
*/
private isPinned(s: ThreadStreamState): boolean {
return s.isRunning || s.pendingInterrupts.length > 0;
}
/** Drop a thread's overlay once the DB is authoritative. No-op while pinned. */
clear(threadId: number): void {
const s = this.states.get(threadId);
if (!s || this.isPinned(s)) return;
this.states.delete(threadId);
this.notify();
}
/** Evict every non-pinned thread except ``exceptThreadId`` (memory bound). */
clearInactive(exceptThreadId: number | null): void {
let changed = false;
for (const [id, s] of this.states) {
if (id === exceptThreadId || this.isPinned(s)) continue;
this.states.delete(id);
changed = true;
}
if (changed) this.notify();
}
// ---- active-stream lifecycle -------------------------------------------
/** Register a new in-flight turn, aborting any previous one first. */
beginActive(threadId: number, controller: AbortController): void {
this.abortActive();
this.active = { threadId, controller };
}
get activeThreadId(): number | null {
return this.active?.threadId ?? null;
}
/** Clear the active handle iff it still points at ``controller``. */
clearActive(controller: AbortController): void {
if (this.active?.controller === controller) this.active = null;
}
/** Abort the in-flight turn's fetch (client disconnect, not a server stop). */
abortActive(): void {
if (this.active) {
this.active.controller.abort();
this.active = null;
}
}
markRecentCancel(): void {
this.recentCancelRequestedAt = Date.now();
}
}
export const chatStreamStore = new ChatStreamStore();

View file

@ -0,0 +1,18 @@
"use client";
import { useCallback, useSyncExternalStore } from "react";
import { chatStreamStore, type ThreadStreamState } from "./store";
/**
* Subscribe to the durable streaming state for a given thread.
*
* Returns the live ``ThreadStreamState`` while a turn is streaming (or
* pending re-hydration from the DB), or ``null`` when the thread has no
* active overlay in which case the page falls back to its DB-hydrated
* messages. State lives in the module-level {@link chatStreamStore}, so it
* survives the chat page unmounting during in-app navigation.
*/
export function useChatStream(threadId: number | null): ThreadStreamState | null {
const getSnapshot = useCallback(() => chatStreamStore.getSnapshot(threadId), [threadId]);
return useSyncExternalStore(chatStreamStore.subscribe, getSnapshot, () => null);
}

View file

@ -6,28 +6,32 @@ export const instagram: ConnectorPageContent = {
name: "Instagram",
icon: IconBrandInstagram,
metaTitle: "Instagram Scraper API for Creator Research | SurfSense",
metaTitle: "Instagram Scraper API for Profiles and Reels | SurfSense",
metaDescription:
"Scrape public Instagram posts, reels, and profiles at scale with the SurfSense Instagram Scraper API. No login, no official API, plus a free tier. Start now.",
"Instagram scraper API for public profiles, posts, and reels. No login or Graph API review. Structured data for AI agents, plus a free tier. Start now.",
keywords: [
"instagram scraper",
"instagram scraper api",
"instagram api",
"instagram api alternative",
"scrape instagram",
"instagram scraping",
"instagram graph api alternative",
"instagram profile scraper",
"instagram post scraper",
"instagram posts scraper",
"instagram reel scraper",
"instagram reels scraper",
"instagram data scraper",
"instagram data api",
"instagram mcp server",
"creator research",
"social listening",
],
h1: "Instagram Scraper API for Creator Research and Social Listening",
h1: "Instagram Scraper API for Profiles, Posts, and Reels",
heroLede:
"The SurfSense Instagram API extracts public posts, reels, and profile details without logging in or registering for the Instagram Graph API. Give your AI agents a live feed of what creators post, so you spot trends and shifts in engagement first.",
"The SurfSense Instagram scraper extracts public profiles, posts, and reels without logging in or registering for the Instagram Graph API. Give your AI agents a live feed of what creators post, so you spot trends and shifts in engagement first.",
transcript: {
prompt: "Pull recent reels from @competitor and summarize what they're posting",
@ -54,48 +58,48 @@ export const instagram: ConnectorPageContent = {
},
extractIntro:
"Every call returns structured items keyed by type. Point the API at a public profile, post, or reel URL, or discover creators with a search query.",
"Every Instagram scraper call returns structured items keyed by type. Point the API at a public profile, post, or reel URL, or discover creators with a search query.",
extractFields: [
{
label: "Posts & Reels",
label: "Posts and reels",
description:
"Caption, hashtags, mentions, like and comment counts, media URLs, dimensions, and timestamp.",
"Caption, hashtags, mentions, like and comment counts, media URLs, dimensions, and timestamp from any public post or reel.",
},
{
label: "Profiles",
label: "Profile data",
description:
"Follower, following, and post counts, bio, external URL, verified and business flags.",
"Follower, following, and post counts, bio, external URL, verified and business flags for public Instagram profiles.",
},
{
label: "Owner & Media",
label: "Owner and media",
description:
"Owner username and id on every item, plus image and video URLs, alt text, and view counts.",
},
],
useCasesHeading: "What teams do with the Instagram API",
useCasesHeading: "What teams do with the Instagram scraper API",
useCases: [
{
title: "Creator and competitor monitoring",
description:
"Track what your competitors and target creators post, and how engagement moves. Feed the stream to an agent that flags viral formats, launches, and shifts in cadence the moment they land.",
"Scrape Instagram profiles and feeds to track what competitors and target creators post, and how engagement moves. Feed the stream to an agent that flags viral formats, launches, and shifts in cadence the moment they land.",
},
{
title: "Content and format research",
description:
"Study a creator's recent posts and reels to see which formats earn the most likes and comments, and turn that into a content calendar your team can act on.",
"Pull a creator's recent posts and reels to see which formats earn the most likes and comments, and turn that into a content calendar your team can act on.",
},
{
title: "Influencer vetting and outreach",
description:
"Verify a creator's follower count, post cadence, and real engagement from public data before you pay for a partnership.",
"Use the Instagram profile scraper to verify follower count, post cadence, and real engagement from public data before you pay for a partnership.",
},
],
comparison: {
heading: "An Instagram API alternative built for agents",
heading: "An Instagram Graph API alternative built for agents",
intro:
"The official Instagram Graph API requires a Business account, app review, and access tokens, and it can't read arbitrary public profiles. Here is how SurfSense compares.",
"The official Instagram Graph API requires a Business account, app review, and access tokens, and it cannot read arbitrary public profiles. SurfSense is an Instagram API alternative for public data. Here is how it compares.",
columnLabel: "Instagram Graph API",
rows: [
{
@ -259,7 +263,12 @@ export const instagram: ConnectorPageContent = {
{
question: "Do I need an Instagram account or the Graph API?",
answer:
"No. This is an independent alternative to the Instagram Graph API, not a wrapper. You do not create a Business account, pass app review, or manage access tokens. You call the SurfSense API with one key, or add the MCP server to your agent, and get structured data back.",
"No. This Instagram scraper API is an independent alternative to the Instagram Graph API, not a wrapper. You do not create a Business account, pass app review, or manage access tokens. You call SurfSense with one key, or add the MCP server to your agent, and get structured profile, post, and reel data back.",
},
{
question: "What Instagram data can I scrape?",
answer:
"Public profiles, posts, and reels. Each item includes captions, hashtags, mentions, engagement counts, media URLs, and owner metadata. Point the Instagram profile scraper at a handle, or pass post and reel URLs directly. Discover creators with search queries when you do not have a URL yet.",
},
{
question: "What are the rate limits?",
@ -274,11 +283,11 @@ export const instagram: ConnectorPageContent = {
],
related: [
{ label: "Reddit API", href: "/reddit" },
{ label: "TikTok API", href: "/tiktok" },
{ label: "YouTube API", href: "/youtube" },
{ label: "Reddit API", href: "/reddit" },
{ label: "Google Maps API", href: "/google-maps" },
{ label: "SERP API", href: "/google-search" },
{ label: "SurfSense MCP Server", href: "/mcp-server" },
{ label: "Read the docs", href: "/docs" },
],
};

View file

@ -6,30 +6,33 @@ export const tiktok: ConnectorPageContent = {
name: "TikTok",
icon: IconBrandTiktok,
metaTitle: "TikTok Scraper API for Trend and Creator Research | SurfSense",
metaTitle: "TikTok Scraper API for Videos and Comments | SurfSense",
metaDescription:
"Scrape public TikTok videos, comments, accounts, and trending feeds by hashtag, profile, or URL with the SurfSense TikTok Scraper API. No approval process or research-API gatekeeping, plus a free tier. Start now.",
"TikTok scraper API for public videos, comments, hashtags, and profiles. No Research API approval. Structured data for AI agents, plus a free tier. Start now.",
keywords: [
"tiktok scraper",
"tiktok scraper api",
"tiktok api",
"tiktok api alternative",
"scrape tiktok",
"tiktok scraping",
"tiktok research api alternative",
"tiktok data api",
"tiktok hashtag scraper",
"tiktok comments scraper",
"tiktok comment scraper",
"tiktok hashtag scraper",
"tiktok profile scraper",
"tiktok video scraper",
"tiktok trending scraper",
"tiktok user search",
"tiktok trend tracking",
"tiktok mcp",
"social listening",
"influencer research tool",
"short-form video analytics",
],
h1: "TikTok Scraper API for Trend and Creator Research",
h1: "TikTok Scraper API for Videos, Comments, and Trend Research",
heroLede:
"The SurfSense TikTok API extracts public videos by hashtag, creator profile, or URL without TikTok's approval-gated Research API. Give your AI agents a live feed of what your market watches and shares, so you catch a trend while it is still rising.",
"The SurfSense TikTok scraper extracts public videos by hashtag, creator profile, or URL, plus comment threads and trending feeds, without TikTok's approval-gated Research API. Give your AI agents a live feed of what your market watches and shares, so you catch a trend while it is still rising.",
transcript: {
prompt: "Find trending TikToks about meal prep this week",
@ -55,46 +58,48 @@ export const tiktok: ConnectorPageContent = {
},
extractIntro:
"Every call returns structured items. Scrape videos from a hashtag, creator profile, or video URL or switch verbs to pull a video's comments, discover accounts by keyword, or fetch the current trending feed.",
"Every TikTok scraper call returns structured items. Scrape videos from a hashtag, creator profile, or video URL, or switch verbs to pull a video's comments, discover accounts by keyword, or fetch the current trending feed.",
extractFields: [
{
label: "Videos",
description: "Caption text, canonical web URL, duration, and cover image for each video.",
description:
"Caption text, canonical web URL, duration, and cover image for each TikTok video.",
},
{
label: "Engagement",
description:
"Play, like, comment, share, and save counts the signal for what is breaking out.",
"Play, like, comment, share, and save counts, the signal for what is breaking out.",
},
{
label: "Authors",
label: "Authors and profiles",
description: "Creator handle, nickname, follower and heart counts, and verified status.",
},
{
label: "Comments",
description:
"Public comment threads on any video URL, so you can read audience reaction beyond vanity views.",
},
{
label: "Music",
description: "Track name, artist, and whether the sound is original — the seed of a trend.",
description: "Track name, artist, and whether the sound is original, the seed of a trend.",
},
{
label: "Hashtags",
description: "Every hashtag on a video, so you can map a topic cluster or campaign.",
},
{
label: "Timestamps",
description: "Created and scraped times so you can track a video's momentum over runs.",
},
],
useCasesHeading: "What teams do with the TikTok API",
useCasesHeading: "What teams do with the TikTok scraper API",
useCases: [
{
title: "Trend and hashtag monitoring",
description:
"Track a hashtag and feed the stream to an agent that flags breakout videos, rising sounds, and formats before they saturate. Catch the wave while it is still rising, not after.",
"Use the TikTok hashtag scraper to track a topic and feed the stream to an agent that flags breakout videos, rising sounds, and formats before they saturate. Catch the wave while it is still rising, not after.",
},
{
title: "Creator and influencer discovery",
description:
"Surface the creators driving a topic, ranked by real engagement, so your team shortlists partners from data instead of a manager's pitch deck.",
"Scrape TikTok profiles and search users by keyword to surface the creators driving a topic, ranked by real engagement, so your team shortlists partners from data instead of a manager's pitch deck.",
},
{
title: "Competitor content analysis",
@ -102,16 +107,16 @@ export const tiktok: ConnectorPageContent = {
"Watch what your category posts and what actually lands. Turn a competitor's best-performing formats and hooks into your own content brief.",
},
{
title: "Campaign and sentiment tracking",
title: "Campaign and comment sentiment",
description:
"Measure how a launch or branded hashtag spreads across TikTok — video count, reach, and engagement over time — then pull the comments on top videos to read how the audience actually reacts, not just a vanity view count.",
"Measure how a launch or branded hashtag spreads across TikTok, then use the TikTok comments scraper on top videos to read how the audience actually reacts, not just a vanity view count.",
},
],
comparison: {
heading: "A TikTok API alternative built for agents",
heading: "A TikTok Research API alternative built for agents",
intro:
"TikTok's official Research API is approval-gated and largely limited to academic and nonprofit use. If you cannot get access or need it for commercial research, here is how SurfSense compares.",
"TikTok's official Research API is approval-gated and largely limited to academic and nonprofit use. If you cannot get access or need commercial TikTok scraping, SurfSense is a TikTok API alternative. Here is how it compares.",
columnLabel: "Official TikTok API",
rows: [
{
@ -154,7 +159,7 @@ export const tiktok: ConnectorPageContent = {
schema: {
requestNote:
"Provide at least one source: urls, profiles, hashtags, or search_queries. Up to 20 sources per call.",
"Provide at least one source: urls, profiles, or hashtags. Up to 20 sources per call. To find accounts by keyword, use the user search verb.",
request: [
{
name: "urls",
@ -175,13 +180,6 @@ export const tiktok: ConnectorPageContent = {
defaultValue: "[]",
description: "Hashtag names to scrape, without the # prefix. Max 20.",
},
{
name: "search_queries",
type: "string[]",
defaultValue: "[]",
description:
"Keyword search terms. Keyword video search is login-walled and returns no videos — use hashtags/profiles/urls for videos, or user_search for accounts. Max 20.",
},
{
name: "results_per_page",
type: "integer",
@ -253,9 +251,19 @@ export const tiktok: ConnectorPageContent = {
"SurfSense reads only public TikTok data, the same videos any logged-out visitor can see. It never logs in and cannot access private or deleted content. As always, review TikTok's terms and your own compliance needs before you run at scale.",
},
{
question: "Does this need the official TikTok API?",
question: "Does this need the official TikTok Research API?",
answer:
"No. It is an independent alternative, not a wrapper on the Research API, so there is no application or approval process. You call the SurfSense API with one key, or add the MCP server to your agent, and get structured videos back.",
"No. This TikTok scraper API is an independent alternative, not a wrapper on the Research API, so there is no application or approval process. You call SurfSense with one key, or add the MCP server to your agent, and get structured videos, comments, and profile data back.",
},
{
question: "What TikTok data can I scrape?",
answer:
"Four verbs: scrape (videos by hashtag, profile, or URL), comments (a video's public comment thread), user search (find accounts by keyword), and trending (the current Explore feed). Each returns structured items and is billed per item returned.",
},
{
question: "Can I scrape TikTok comments and hashtags?",
answer:
"Yes. Pass a video URL to the comments endpoint for the public comment thread. Pass hashtag names or /tag/ URLs to the TikTok hashtag scraper to pull videos under that tag. Keyword video search is login-walled on TikTok, so hashtags and direct URLs are the reliable discovery paths; to find accounts by keyword, use the user search verb.",
},
{
question: "What are the rate limits?",
@ -265,18 +273,14 @@ export const tiktok: ConnectorPageContent = {
{
question: "Can I scrape a specific creator's videos?",
answer:
"Pass a profile or profile URL and you always get the account's metadata — name, followers, bio, verification. TikTok often withholds the profile video list from automated clients, so that list can come back empty even for a public account; for reliable video results, scrape by hashtag or by a direct video URL.",
},
{
question: "What TikTok data can I scrape?",
answer:
"Four verbs: scrape (videos by hashtag, profile, or URL), comments (a video's public comment thread), user search (find accounts by keyword — the reliable discovery path, since keyword video search is login-walled), and trending (the current Explore feed). Each returns structured items and is billed per item returned.",
"Pass a profile or profile URL and you always get the account's metadata: name, followers, bio, verification. TikTok often withholds the profile video list from automated clients, so that list can come back empty even for a public account. For reliable video results, scrape by hashtag or by a direct video URL.",
},
],
related: [
{ label: "Reddit API", href: "/reddit" },
{ label: "Instagram API", href: "/instagram" },
{ label: "YouTube API", href: "/youtube" },
{ label: "Reddit API", href: "/reddit" },
{ label: "Google Maps API", href: "/google-maps" },
{ label: "SERP API", href: "/google-search" },
{ label: "Web Crawl API", href: "/web-crawl" },

View file

@ -68,3 +68,17 @@ export function formatRelativeFutureDate(dateString: string): string {
export function formatThreadTimestamp(dateString: string): string {
return format(new Date(dateString), "MMM d, yyyy 'at' h:mm a");
}
/**
* Format a chat message timestamp for inline display under a bubble.
* Locale-aware, 12-hour clock. Example: "Jul 13, 10:42 PM".
*/
export function formatMessageTimestamp(date: Date): string {
return date.toLocaleDateString(undefined, {
month: "short",
day: "numeric",
hour: "numeric",
minute: "2-digit",
hour12: true,
});
}

View file

@ -23,7 +23,11 @@ assert.deepEqual(payload, {
query: "<query>",
});
const snippets = buildSnippets("https://api.example.com", "/api/v1/workspaces/1/scrapers/x/y", payload);
const snippets = buildSnippets(
"https://api.example.com",
"/api/v1/workspaces/1/scrapers/x/y",
payload
);
// Every popular language is present.
assert.deepEqual(

View file

@ -11,9 +11,7 @@ export function formatCost(costMicros: number | null | undefined): string {
/** One meter as a per-1k rate, e.g. 3500 micros/place -> "$3.50 / 1k places". */
export function formatRate(meter: ScraperPricingMeter): string {
const perThousand = (meter.micros_per_unit * 1000) / 1_000_000;
const dollars = Number.isInteger(perThousand)
? perThousand.toString()
: perThousand.toFixed(2);
const dollars = Number.isInteger(perThousand) ? perThousand.toString() : perThousand.toFixed(2);
return `$${dollars} / 1k ${meter.unit}s`;
}

View file

@ -8,13 +8,7 @@
type JsonObject = Record<string, unknown>;
export type FieldKind =
| "string"
| "string_array"
| "integer"
| "number"
| "boolean"
| "enum";
export type FieldKind = "string" | "string_array" | "integer" | "number" | "boolean" | "enum";
export interface FormField {
name: string;

View file

@ -29,6 +29,7 @@ import {
QwenIcon,
RecraftIcon,
ReplicateIcon,
RequestyIcon,
SambaNovaIcon,
TogetherAiIcon,
VertexAiIcon,
@ -117,6 +118,8 @@ export function getProviderIcon(
return <RecraftIcon className={cn(className)} />;
case "REPLICATE":
return <ReplicateIcon className={cn(className)} />;
case "REQUESTY":
return <RequestyIcon className={cn(className)} />;
case "SAMBANOVA":
return <SambaNovaIcon className={cn(className)} />;
case "TOGETHER_AI":

View file

@ -1,6 +1,6 @@
{
"name": "surfsense_web",
"version": "0.0.31",
"version": "0.0.32",
"private": true,
"packageManager": "pnpm@10.26.0",
"description": "SurfSense Frontend",