find-marketing-agency

find-marketing-agency

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:marketing_agency and add the relevant service_provided: tags.

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/pro_services/fields[?include_values=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:

``bash ( 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 SERVICEGRAPH_API_KEY=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.

Recipes

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.
2. User picks N to fully enrich. POST /unlocks with all of them = 10×N credits, single atomic charge, detail bundles returned.
3. Within 30-day TTL, repeated unlock POSTs are free.

Gotchas

• Always pin industry:marketing_agency. Without it, service_provided: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, service_provided, state, ratings. They DON'T include url, phone_primary, email_primary, legal_name, address_full, full platforms. Those require an unlock.
• not_found / not_in_dataset 404 is not a bug. Apex isn't in pro_services (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 | filter_parse_error | position included; fix and re-validate with /check. | | 400 | kind_in_filter | Strip any kind: from filter — URL is authoritative. | | 400 | field_not_in_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 | not_found / not_in_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