find-pr-agency#

Drive the ServiceGraph API ( https://api.servicegraph.co) to find, shortlist, and enrich US PR and communications agencies via the pro_services dataset.

Always pin service_provided:public-relations. Note: the catalog's nominal industry:pr_comms value returns zero firms in the live release — PR/comms firms are tagged with service_provided:public-relations instead, typically under adjacent industries ( marketing_agency, other_pro_services). Pin the service tag, not the industry. Sub-types (media relations, crisis, IR, public affairs, healthcare PR, tech PR, B2B PR, internal comms, brand reputation) are NOT separate tags — sub-type specialization is a keyword substring search on firm text.

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

Sibling skills — defer when scope is broader#

If the user wants a multi-service marketing engagement (PR plus content plus paid plus social), defer to find-marketing-agency — that skill covers full-service shops where PR is one of several service lines.

This skill is correct when PR/comms is the primary deliverable — launches, media relations, crisis, IR, public affairs.

When NOT to use this skill#

• "Write me a press release / draft these talking points" → DIY work.
• In-house comms/PR hires (Head of Comms, PR Manager).
• PR-software comparisons (Cision, Muck Rack, Prowly).
• Influencer-marketplace asks — that's paid media; defer to find-marketing-agency or refuse for marketplace product questions.
• "Explain how earned media works" → knowledge question.
• Non-US firms.
• Individual freelance PR people / publicists.

MCP server (preferred for authed calls)#

If your harness has the ServiceGraph MCP server loaded (tools containing servicegraph in the name), prefer those — credentials stay in the harness's OAuth 2.1 + PKCE sandbox and 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_…). No anonymous tier.

EndpointCostUse it forGET /v1/datasets/pro_services/fields[?include_values=1]freeConfirm public-relations is in the service_provided value list.GET /v1/datasets/pro_services/check?filter=…freeValidate filter.POST /v1/datasets/pro_services/translate-intentfree{intent} → LLM-generated DSL filter + sanity count.GET /v1/datasets/pro_services/search?filter=…&limit=freeBrief firm cards + per-row unlock hint + total.GET /v1/datasets/pro_services/:apexfreeOne row brief; detail only if unlocked.POST /v1/datasets/pro_services/unlocks10 credits / firm{apexes:[...]} ≤100; atomic; 30-day TTL on detail.GET /v1/me/creditsfreeBalance.

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.

Auth#

Tokens are vk_* API keys minted in the dashboard. Keep the token out of the LLM context — never read .env* files; dispatch every authed call through a shell wrapper.

1. Try the call first 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' )
   
   

2. On 401 unauthorized, prompt the user:

   "Open https://servicegraph.co/profile/api-keys, create a key, and 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."

3. Retry after the user signals ready.

Filter DSL#

GitHub-search-style.

text

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: AND binds tighter than OR (use parens); comma list = OR within one predicate; negation is -x or NOT x (no negative literals inside comma lists); bareword = keyword search (multi-word phrases must be quoted or split).

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

text

service_provided:public-relations tech state:NY
service_provided:public-relations healthcare
service_provided:public-relations b2b saas
service_provided:public-relations crisis
service_provided:public-relations "investor relations"
service_provided:public-relations ipo state:NY,CA
service_provided:public-relations "public affairs" state:DC
service_provided:public-relations rating>=4 has:clutch

Sub-type / vertical → keyword mapping:

User asks forAdd as keyword(s)Tech / startup PRtech, startup, saasHealthcare / pharma PRhealthcare, pharma, biotechCrisis commscrisisInvestor relations / IR"investor relations", ir, ipoB2B PRb2bPublic affairs"public affairs"Brand reputation"brand reputation", reputationInternal communications"internal communications", "internal comms"Earned media / media relations"earned media", "media relations"

Identifying firms — apex#

Firms are identified by their apex domain ( edelman.com, not www.edelman.com/about).

Recipes#

A. Tech PR for a Series-B announcement#

User: "Tech PR agency in NY for our Series-B announcement."

text

GET /v1/datasets/pro_services/search?filter=service_provided:public-relations+tech+state:NY&limit=10
# → 10 brief cards + total + per-row unlock.status

# Present, get 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"] }

B. IR firms for an IPO#

User: "Three IR firms for our upcoming IPO roadshow."

text

GET /v1/datasets/pro_services/search?filter=service_provided:public-relations+("investor relations" OR ir)+ipo&limit=10

C. Crisis comms (urgent)#

User: "Crisis comms help — brand reputation issue blowing up online."

text

GET /v1/datasets/pro_services/search?filter=service_provided:public-relations+crisis&limit=10

Skip the validation hop and present briefs immediately given the urgency.

D. Healthcare / regulatory PR#

User: "Healthcare PR agency familiar with FDA regulatory comms."

text

GET /v1/datasets/pro_services/search?filter=service_provided:public-relations+healthcare+(fda OR regulatory)&limit=10

E. Indirect intent — "we need press"#

User: "We need press for our Series-B — get us into TechCrunch, WSJ, and the trade press."

That's product-launch / tech PR. Either translate by hand:

text

GET /v1/datasets/pro_services/search?filter=service_provided:public-relations+(tech OR startup)+(launch OR series-b)&limit=10

…or hand the intent off:

text

POST /v1/datasets/pro_services/translate-intent
  { "intent": "PR agency to get our Series-B into TechCrunch and trade press" }

If thin, drop the launch/series-b keyword — most tech PR firms run launches as a default deliverable.

F. Public affairs (state government)#

User: "Public affairs firms with state-government experience in California."

text

GET /v1/datasets/pro_services/search?filter=service_provided:public-relations+"public affairs"+state:CA&limit=10

G. BYO apex list — enrich domains#

User pastes 8–20 PR-firm 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, atomic, detail returned.
3. Re-runs within 30-day TTL are free.

Gotchas#

• Pin service_provided:public-relations, not industry:pr_comms. The industry value is empty in the live catalog; PR firms sit under adjacent industries. Without the service pin, "tech PR" / "crisis" / "investor relations" keywords leak into general marketing.
• Defer to find-marketing-agency for full-service marketing. When PR is one of several service lines (PR + content + paid + social), the marketing-agency skill is the right fire.
• Sub-types are keyword-only. Multi-word sub-types split into ANDed barewords unless quoted ( investor relations → investor AND relations; "investor relations" → one phrase).
• "Write me a press release" / "draft talking points" is do-the-work. Refuse and offer to find a firm if the user wants to engage one.
• Influencer marketing is NOT PR. Influencer marketplaces (Aspire, Grin) and influencer outreach are paid-media work; defer to find-marketing-agency or refuse for marketplace product questions.
• PR-software comparisons (Cision, Muck Rack, Prowly) are NOT procurement.
• Briefs DO include apex, name, location, 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 = not in pro_services. Not charged. Skip.
• Unlock is atomic. 5 apexes either all charge (up to 50 credits) or none charge on 402.
• Within-TTL re-views are free ( was_cached:true).

Errors#

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

StatusCodeWhat to do400filter_parse_error``position included; fix and re-validate with /check.400kind_in_filterStrip any kind: from filter — URL is authoritative.400field_not_in_datasetDrop the disallowed field.400invalid_apexRe-normalize to apex domain.401unauthorized / invalid_audienceRe-prompt for fresh vk_….402insufficient_credits``needed and balance in payload; nothing charged.404not_found / not_in_datasetSkip; not charged.429rate_limitedHonor Retry-After.

End-to-end example#

User: "Three tech PR agencies in NY for a Series-B announcement, ideally with 4-star ratings and Fortune 500 client experience."

text

GET /v1/datasets/pro_services/fields?include_values=1
GET /v1/datasets/pro_services/check?filter=service_provided:public-relations+tech+state:NY+rating>=4
GET /v1/datasets/pro_services/search?filter=...&limit=10
# Present briefs. "Unlocking 3 = 30 credits, 30-day TTL."
POST /v1/datasets/pro_services/unlocks
  { "apexes": ["firm-a.com", "firm-b.com", "firm-c.com"] }
GET /v1/me/credits