> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). For curated orientation and workflow guidance, start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for agent onboarding and crawl rules, use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for the full endpoint list with links to pages like this one, use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt); for one platform's parameters and curls, use [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need structured JSON for tool registration.

## This page

- **On-site (HTML):** [https://www.socialfetch.dev/docs/teams](https://www.socialfetch.dev/docs/teams)
- **Markdown (.mdx) URL:** [https://www.socialfetch.dev/docs/teams.mdx](https://www.socialfetch.dev/docs/teams.mdx)

## API base URL and authentication

- **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev`
- **Authentication:** send `x-api-key: sfk_...` on `/v1/**` and `/v2/**` routes unless the operation is explicitly anonymous (check OpenAPI `security`, the [API reference hub](https://www.socialfetch.dev/docs/api.mdx), [`/llms.txt`](https://www.socialfetch.dev/llms.txt), or [`/llms.json`](https://www.socialfetch.dev/llms.json) for each route).
- **OpenAPI JSON:** [https://www.socialfetch.dev/openapi.json](https://www.socialfetch.dev/openapi.json)

## Recommended docs entrypoints (this site)

- [Documentation overview](https://www.socialfetch.dev/docs.mdx) — top-level orientation (markdown).
- [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx) — authenticate with `x-api-key`, validate auth with `whoami`, and understand the JSON envelope.
- [SDK](https://www.socialfetch.dev/docs/sdk.mdx) — official TypeScript SDK guide, including `SocialFetchClient`, `Result`, and `unwrap()`.
- [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — every operation with identifiers, pagination, outcomes, media download, credits, and its SDK method. Generated from OpenAPI, so use it for route selection instead of scanning individual pages.
- [Recipes](https://www.socialfetch.dev/docs/recipes.mdx) — copyable workflows (brand monitoring, transcripts, Ad Library, creator scoring, Reddit research) with credit callouts and SDK examples.
- [Integrations](https://www.socialfetch.dev/docs/integrations.mdx) — MCP for AI clients, n8n verified node, Apify Store Actors, Make custom app, SDK, and REST API connection paths.
- [MCP product page](https://www.socialfetch.dev/mcp) — hosted MCP overview, OAuth, Skills install.
- [MCP integration](https://www.socialfetch.dev/docs/integrations/mcp.mdx) — hosted `/mcp` server, OAuth, Cursor/VS Code/Claude install snippets, 237 endpoint tools, plus docs_search/docs_read for implementation help.
- [n8n integration](https://www.socialfetch.dev/docs/integrations/n8n.mdx) — install `n8n-nodes-socialfetch`, credentials, and workflow examples.
- [Apify integration](https://www.socialfetch.dev/docs/integrations/apify.mdx) — Store Actors under @social-fetch, PPE billing, dataset export, and quick start.
- [Make integration](https://www.socialfetch.dev/docs/integrations/make.mdx) — custom app modules for Make scenarios, API key credentials, and module catalog.
- [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt) — every documented operation with a direct link to that route's agent-readable markdown page (prefer this over parsing OpenAPI).
- [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt) — per-platform endpoint files generated from OpenAPI (parameters, credits, curls).
- [`/agents.txt`](https://www.socialfetch.dev/agents.txt) — agent crawl/onboarding file with capabilities, auth rules, and allowlist.
- [`/llms.json`](https://www.socialfetch.dev/llms.json) — structured machine-readable operation inventory with parameter names, pagination, outcomes, credits, and SDK mapping.
- [API reference hub](https://www.socialfetch.dev/docs/api.mdx) — human-friendly index of operations with links into generated pages.
- [Errors](https://www.socialfetch.dev/docs/errors.mdx) — shared error envelope and HTTP status guidance.
- [Credits](https://www.socialfetch.dev/docs/credits.mdx) — metering, `402`, and planning batch jobs.
- Outcome semantics such as `found`, `not_found`, and `private` are documented in [Errors](https://www.socialfetch.dev/docs/errors.mdx) and on operation pages when present in the OpenAPI contract.

## Markdown docs convention

- Every docs page has a markdown twin: append **`.mdx`** to the docs pathname (for example `/docs/quickstart` → `/docs/quickstart.mdx`).
- Agents that send `Accept: text/markdown` on `/docs/**` HTML URLs may receive markdown directly (same URL, `Vary: Accept`).
- Published blog posts use the same convention: `/blog/{slug}` → `/blog/{slug}.mdx`, or `Accept: text/markdown` on the HTML URL (`Vary: Accept`).

---
# Teams and workspaces (https://www.socialfetch.dev/docs/teams)

A **workspace** is where your credits, subscription, API keys, monitors, and webhook endpoints live. Every account starts with a personal workspace, and you can own up to 5 shared workspaces in addition to it. Invite teammates to a workspace and they use the same balance and the same bill, each with their own sign-in and their own keys.

Credits, plans, and payment methods belong to each workspace and are billed to that workspace. Credits cannot be transferred between workspaces. If you bought credits in the wrong workspace, [contact us](/contact) and we can move them on request. The first-purchase bonus applies once per person, in your personal workspace only.

Accounts sign in with Google, GitHub, or email and password. Every account can add two-factor authentication (an authenticator app plus backup codes) from **Settings**.

## Creating a workspace

Create a shared workspace from the workspace switcher at the top of the dashboard. You can own up to 5, and create up to 3 in a day. Names must be 2 to 60 characters and can't imitate Social Fetch, Stripe, or an official or reserved name, including lookalike spellings. Each workspace starts empty, with its own balance, keys, and bill.

## Roles

| Role        | What they can do                                                                                                                   |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Owner**   | Everything: billing, plan, members, ownership transfer.                                                                            |
| **Admin**   | Manage people, keys, monitors, and webhooks; buy credit packs. Cannot change the plan, cards, or auto-refill.                      |
| **Member**  | Use the API and the dashboard with their own keys, monitors, and webhook endpoints. Members only see and change what they created. |
| **Billing** | See usage and manage payment. Cannot use the API and does not take a seat.                                                         |

A person can hold more than one role. A workspace always has at least one owner.

### Custom roles

Workspaces with the custom roles add-on, and Enterprise workspaces, can add their own roles beside these four. An owner builds one under **Team → Roles** by ticking the permissions it should hold, then gives it to someone when inviting them or from the members menu (**Change role**). Custom roles are an add-on on Scale ($49 per month), self-serve from **Billing → Add-ons**, and included with Enterprise.

A custom role can grant API keys, monitors, webhooks, connected AI apps, usage, request logs, billing read and buying credit packs, the activity log, and seeing who is in the workspace. It can never grant workspace settings, adding or removing members, invitations, single sign-on, directory sync, billing management (plan and cards), or exporting the activity log. Like Members, people with a custom role manage only their own keys, monitors, and webhooks. A custom role that grants none of keys, monitors, webhooks, or AI apps takes no seat. A role that someone still holds can't be deleted.

## Inviting people

Owners and admins invite by email from **Team**. The invitation is tied to that address: the person signs in with the same email (Google, GitHub, or email and password), then accepts. Invitations expire after 7 days, can be resent or cancelled, and never reveal the workspace to anyone else.

Workspaces on Scale (as an add-on) and Enterprise can also add people through [single sign-on and directory sync](/docs/single-sign-on).

## Seats

How many people a workspace can hold depends on its plan: just you on Pay as you go and Starter, up to 5 on Growth, and up to 25 on Scale, with more on request. Buying credits does not add seats. Enterprise contracts can set their own limit. Pending invitations count towards seats; the Billing role never does. There is no per-seat price. Need more? [Contact us](/contact).

If you move to a plan, or cancel to Pay as you go, with fewer seats than people in the workspace, you're asked to confirm first. Nobody is removed automatically, but you can't invite anyone new until you're back within the limit.

## API keys

Keys belong to the person who created them and act in the workspace they were created in. Requests made with a workspace key spend the workspace's credits. `GET /v1/whoami` always returns a `workspace` object (`id`, `name`, `role`, `isPersonal`) telling you which workspace the key acts in. **Usage** shows spend per teammate and per key, and you can export it as CSV.

Owners and admins can cap what one key spends per month (**API keys → Limit**). A key at its limit is refused with `402 insufficient_credits` and a message saying it reached its monthly limit; your balance is not touched.

When someone leaves a workspace, the keys they made for it stop working immediately. Clients receive `403 forbidden` with a `reason` field:

| `reason`                | Meaning                                                                                                                            |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `key_owner_removed`     | The person who created the key is no longer in the workspace. Create a new key.                                                    |
| `key_owner_role`        | The role of the person who created the key no longer allows API use (for example Billing). Create a new key with a role that does. |
| `workspace_suspended`   | The workspace has been suspended.                                                                                                  |
| `workspace_deleted`     | The workspace no longer exists.                                                                                                    |
| `workspace_unavailable` | The workspace can't be used right now. [Contact us](/contact).                                                                     |

`GET /v1/balance` returns the balance of the workspace the key belongs to.

## AI apps (MCP)

If you belong to more than one workspace, you choose which one an AI app spends when you connect it. Requests from that app use that workspace's credits.

## Monitors and webhooks

Monitors and webhook endpoints belong to the workspace and are billed to it. Owners and admins manage all of them; members manage their own. The HTTP API for monitors and webhooks requires an owner or admin key; members use the dashboard.

A monitor created with an API key follows that key. Its checks count against the key's monthly limit and are skipped, with a notice, when the limit is reached. If the key is deleted, disabled, or expires, the monitor is paused with a notice; resume it to run on the workspace's credits. Monitors created in the dashboard aren't tied to a key.

## Activity log

Owners and admins can see who invited, removed, or changed the role of a teammate, and when, under **Team → Activity**. Entries are deleted after 90 days (a year on Scale).

## Leaving and ownership

Anyone can leave a workspace, except its only owner. To hand a workspace over, an owner opens the members menu and chooses **Transfer ownership**. The previous owner's saved cards are removed from the workspace when ownership changes, so the new owner must add a payment method; until they do, subscription renewals and auto-refill fail. An account can't be deleted while its workspace still has teammates; remove them or transfer ownership first.

Closing a workspace, transferring ownership, and similar sensitive actions need you to have signed in within the last 10 minutes. If it's been longer, you're prompted to **Sign in again** before it goes through.

## Closing a workspace

Closing a workspace requires a typed acknowledgement that its remaining credits will be forfeited. If you created the workspace and are its only owner, it closes immediately. If another owner asks to close it, it closes after 24 hours. Remaining credits are forfeited once the 30-day restoration window ends. Within those 30 days an owner can [contact us](/contact) to restore the workspace or move its credits.