find-marketing-agency

Overview

Drive the ServiceGraph API (https://api.servicegraph.co) to find,

shortlist, and enrich US marketing agencies via the pro_services

dataset. The catalog has tens of thousands of US marketing firms

tagged across ~26 service sub-tags including branding,

content-marketing, ppc, social-media-marketing, email-marketing,

web-design, video-production, inbound-marketing,

marketing-strategy, conversion-optimization, and

ecommerce-marketing. (Note: there is no performance-marketing or

demand-gen / demand-generation tag — those user-phrasings map to

inbound-marketing / marketing-strategy / conversion-optimization

plus a keyword fallback.)

Always pin industry:marketing_agency. This skill exists to do

that automatically — the user shouldn't have to think about catalog

taxonomy.

Any HTTP client works (curl, fetch, requests). Examples below use curl.

Sibling skills — defer when scope is narrow

If the user's ask is strictly one of the following, defer to the

dedicated skill:

• Strictly SEO/search-ranking work → find-seo-agency
• Strictly web/app/software development → find-web-developer /

find-software-developer

If the user wants a marketing agency that also does SEO or web work

as part of a broader engagement, this skill is correct — pin

industry:marketingagency and add the relevant serviceprovided:

tags.

Prerequisites

• ServiceGraph access, either:
• the ServiceGraph MCP server (https://mcp.servicegraph.co) loaded in

your harness — this plugin's .mcp.json wires it up; OAuth 2.1 + PKCE

keeps credentials in the harness sandbox — or

• a ServiceGraph API key (vk_…, minted at

) available as

SERVICEGRAPHAPIKEY in the environment or .env.local for the REST

path (setup steps under Auth below).

• An HTTP client for the REST path — the examples use curl.

Instructions

The loop is free-first: discovery, validation, search, and brief reads cost

nothing; only unlock after the user confirms the spend.

1. Pick the call path — the ServiceGraph MCP tools if loaded, otherwise the

REST flow (MCP server and Auth sections below).

1. GET /v1/datasets/proservices/fields?includevalues=1 — confirm the

fields and values you plan to filter on exist.

1. Build the filter (Filter DSL below) and validate it with

GET /v1/datasets/pro_services/check — or draft it from plain English via

POST /v1/datasets/pro_services/translate-intent.

1. GET /v1/datasets/pro_services/search — present the free brief cards and

let the user pick.

1. Quote the unlock cost (10 credits per row, 30-day TTL) and get an explicit

go-ahead.

1. POST /v1/datasets/pro_services/unlocks with the chosen apexes; report the

revealed detail.

1. GET /v1/me/credits to report the remaining balance when asked.

MCP server (preferred for authed calls)

If your harness has the ServiceGraph MCP server loaded (recognizable

by tool names containing servicegraph), prefer those tools — the

harness handles credentials in its own sandbox via OAuth 2.1 + PKCE,

so no token enters LLM context. Otherwise use the REST flow below.

API surface (dataset id: pro_services)

Every endpoint requires the bearer (Authorization: Bearer vk_…).

There is no anonymous tier.

Endpoint	Cost	Use it for
GET /v1/datasets/proservices/fields[?includevalues=1&q=]	free	Filter-field catalog + DSL grammar. Call first per session.
GET /v1/datasets/pro_services/values/:field[?q=&limit=]	free	Enumerate values for one field.
GET /v1/datasets/pro_services/check?filter=…	free	Validate a filter. Returns {valid, normalized} or {valid:false, error}.
POST /v1/datasets/pro_services/translate-intent	free	{intent} → LLM-generated DSL filter + sanity count.
GET /v1/datasets/pro_services/search?filter=…&limit=&offset=	free	Brief firm cards + per-row unlock hint + total.
GET /v1/datasets/pro_services/:apex	free	Single row brief; detail block only if unlocked.
POST /v1/datasets/pro_services/unlocks	10 credits / firm	{apexes:[...]} ≤100. Atomic batch; 30-day TTL on detail; was_cached:true rows free.
GET /v1/me/credits	free	Balance.

Cost model. Discovery / validation / search / brief reads are

free. Detail (url, phone, email, social, address, full platforms

map) costs 10 credits per firm and lasts 30 days. Re-fetching

an unlocked firm within TTL is free.

Auth

Tokens are vk_* API keys minted in the dashboard.

Keep the token out of the LLM context — never read .env* into

your context; dispatch every authed call through a shell wrapper.

1. Just try the call through a shell wrapper that sources

.env.local:

   ( set -a; [ -f .env.local ] && . ./.env.local; set +a;
     curl -sS -H "Authorization: Bearer $SERVICEGRAPH_API_KEY" \
          'https://api.servicegraph.co/v1/datasets/pro_services/fields' )

1. On 401 unauthorized, prompt the user (don't accept the key in chat):

> "Open https://servicegraph.co/profile/api-keys, sign in,

> click Create key, and copy the vk_… value. Then add

> SERVICEGRAPHAPIKEY=vk_… to .env.local here (or export it

> in your shell). Tell me when done. Please don't paste the key

> into chat."

1. Retry the same call after the user signals ready. A later 401

means the key was rotated/revoked — re-prompt.

Filter DSL

GitHub-search-style.

filter   := orExpr
orExpr   := andExpr ("OR" andExpr)*
andExpr  := notExpr (("AND")? notExpr)*    # whitespace = implicit AND
notExpr  := ("NOT" | "-") notExpr | atom
atom     := "(" filter ")" | predicate
predicate:= IDENT op valueOrList | bareword
op       := ":" | "=" | ">=" | "<=" | ">" | "<"
valueOrList := value ("," value)*
value    := IDENT | NUMBER | tagAtEvidence
tagAtEvidence := IDENT "@" ("low"|"medium"|"high")
bareword := IDENT | NUMBER          # → keyword:<bareword>

Four rules that bite:

1. AND binds tighter than OR. a OR b c parses as a OR (b AND c). Use parens.
2. Comma list = OR within one predicate. state:CA,NY,TX = any of three.
3. Negation is -x or NOT x. state:CA,-NY is rejected; use state:CA -state:NY.
4. Bareword = keyword search. Free-text substring across name / brand / title / meta / legal_name. Multiple barewords AND. Wrap multi-word phrases in double quotes (keyword:"foo bar").

Marketing-flavored examples (validate yours with /check):

industry:marketing_agency service_provided:branding@high
industry:marketing_agency service_provided:ppc service_provided:content-marketing
industry:marketing_agency state:CA,NY -company_size_signal:solo
industry:marketing_agency (service_provided:inbound-marketing@high OR service_provided:marketing-strategy@high)
b2b industry:marketing_agency service_provided:content-marketing@high
industry:marketing_agency rating>=4 review_count_total>=20 has:clutch
industry:marketing_agency NOT (service_provided:seo OR service_provided:web-development)

Identifying firms — apex

Firms are identified by their apex domain (ogilvy.com, not

www.ogilvy.com/about). Strip user-supplied URLs to the apex before

calling :apex endpoints or building unlock batches.

Output

All responses are JSON.

• Search returns free brief firm cards — apex, name, location, and

rating signals — plus a per-row unlock hint and the match total. Briefs

never include url, phoneprimary, emailprimary, legal_name,

address_full, or the full platforms map.

• Unlock (POST …/unlocks) returns each unlocked firm's detail block —

contact fields, address, socials, the platforms map — plus per-item

billing; detail stays readable for 30 days.

• Errors arrive as a JSON envelope

{"error": {"code": "…", "message": "…"}} — see Errors below.

Examples

A. Branding agency in a state

User: "Three B2B branding agencies in California for a Series-A SaaS company."

GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+state:CA+service_provided:branding@high+b2b&limit=10
# → 10 brief cards + total + per-row unlock.status

# Present, get user's pick of 3. "Unlocking 3 = 30 credits, 30-day TTL."
POST /v1/datasets/pro_services/unlocks
  { "apexes": ["firm-a.com", "firm-b.com", "firm-c.com"] }
# → brief + detail for all 3

B. PPC + ecommerce vertical

User: "PPC shop that specializes in ecommerce."

The catalog has a real ecommerce-marketing tag — pin it alongside

PPC for tighter shortlists than relying on the ecommerce keyword

alone:

GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:ppc+service_provided:ecommerce-marketing&limit=10

C. Multi-tag intersection — content + email + B2B vertical

User: "Content marketing partner for a SaaS launch — should also do email."

GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:content-marketing@high+service_provided:email-marketing+saas

If the NY-area pool collapses with a fintech/saas keyword (it

tends to — vertical pins under-perform on agency copy), drop the

keyword and surface vertical experience to the user from briefs.

D. Performance / demand-gen (indirect intent)

User: "Someone to run our quarterly demand-gen campaigns and own the funnel."

The catalog has no performance-marketing / demand-gen /

demand-generation tag — map to inbound-marketing,

marketing-strategy, or conversion-optimization, plus a keyword

for the user's wording:

GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+(service_provided:inbound-marketing@high OR service_provided:marketing-strategy@high OR service_provided:conversion-optimization@high)+(demand OR funnel)&limit=10

If breakdowns are thin, drop @high or fall back to pure keyword.

Alternatively, use the intent translator:

POST /v1/datasets/pro_services/translate-intent
  { "intent": "agency to run quarterly demand-gen campaigns and own the funnel" }

E. Quality threshold (third-party signals)

User: "Compare three social media agencies that have worked with Fortune 500 — high evidence."

GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:social-media-marketing@high+rating>=4+review_count_total>=20+has:clutch&limit=10

fortune 500 is hard to filter structurally; let the user pick from

briefs or add fortune as a keyword.

F. DTC ecommerce agencies

User: "Paid-social agency for our DTC apparel brand."

GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:ecommerce-marketing+service_provided:social-media-marketing+dtc&limit=10

G. Video production

User: "Video production studio for a 90-second product launch film, NYC or LA."

GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:video-production+state:NY,CA&limit=10

State is HQ-only; surface city from the unlocked detail for NYC-vs-LA disambiguation.

H. BYO apex list — enrich domains

User pastes 8–20 domains:

1. GET /v1/datasets/pro_services/:apex per domain — free brief

(404 = not in catalog, no charge). Flag misses.

1. User picks N to fully enrich. POST /unlocks with all of them =

10×N credits, single atomic charge, detail bundles returned.

1. Within 30-day TTL, repeated unlock POSTs are free.

Gotchas

• Always pin industry:marketingagency. Without it, serviceprovided:branding matches design firms, IT services, and others.
• Defer to sibling skills for narrow asks. SEO-only → find-seo-agency. Strictly web/app development → find-web-developer / find-software-developer.
• Briefs DO include apex, name, industry, serviceprovided, state, ratings. They DON'T include url, phoneprimary, emailprimary, legalname, address_full, full platforms. Those require an unlock.
• notfound / notindataset 404 is not a bug. Apex isn't in proservices (might be in another dataset). Skip; not charged.
• Catalog is US-only B2B. Refuse non-US asks, individual freelancers, and personal-brand consulting for the user themselves.
• Multi-word phrases must be split or quoted. b2b saas parses as two AND'd keywords; "b2b saas" is one phrase.
• Unlock is atomic. POST /unlocks with 5 apexes either charges (up to) 50 credits or leaves balance untouched on 402. Plan the batch.
• Within-TTL re-views are free. Re-running unlock on an apex still inside its 30-day window returns was_cached:true.

Errors

JSON envelope: {"error": {"code": "...", "message": "..."}}.

Status	Code	What to do
400	filterparseerror	position included; fix and re-validate with /check.
400	kindinfilter	Strip any kind: from filter — URL is authoritative.
400	fieldnotin_dataset	Field isn't allowed on pro_services; drop it.
400	invalid_apex	Re-normalize to apex.
401	unauthorized / invalid_audience	Re-prompt for a fresh vk_….
402	insufficient_credits	needed and balance in payload; nothing charged.
404	notfound / notin_dataset	Skip; not charged.
429	rate_limited	Honor Retry-After.

End-to-end example

User: *"Shortlist three B2B branding agencies in California for a

Series-A SaaS company — high evidence on branding, ideally with at

least a 4-star rating."*

# 1. Discover (once per session)
GET /v1/datasets/pro_services/fields?include_values=1
# Confirms 'branding' is in service_provided, rating is numeric.

# 2. Validate + scope (free)
GET /v1/datasets/pro_services/check?filter=industry:marketing_agency+state:CA+service_provided:branding@high+rating>=4+b2b

# 3. Search briefs (free)
GET /v1/datasets/pro_services/search?filter=...&limit=10
# → 10 cards + total + per-row unlock.status

# 4. Present, get pick of 3. "Unlocking 3 firms = 30 credits, 30-day TTL."

# 5. Atomic unlock (charges 30 credits)
POST /v1/datasets/pro_services/unlocks
  { "apexes": ["firm-a.com", "firm-b.com", "firm-c.com"] }

# 6. (Optional) Confirm balance
GET /v1/me/credits

Resources

• Upstream source:
• ServiceGraph API: — keys at

• Hub skill: servicegraph (this plugin) — the dataset-agnostic entry point

when the user names ServiceGraph explicitly.