# Read tools

33 tools that only fetch data. Each wraps one public GraphQL query field and executes it verbatim, so the arguments, filters, and result shapes are the ones documented on that field's reference page.

Read tools are annotated `readOnlyHint: true` and `idempotentHint: true`, so an agent may retry one freely. They are available to every valid credential, including an OAuth connection without the write scope.

> **Start with getWorkspaces** — It is the one tool that needs no workspace, and it returns the ids every other tool needs. See [Connect a client](/api/v2/docs/mcp/connect).

## searchItems

Wraps [`items`](/api/v2/docs/queries/items).

Search archived social content (Instagram, TikTok, YouTube) for the current workspace.

## searchCreators

Wraps [`creators`](/api/v2/docs/queries/creators).

Search creators (influencers) tracked for the current workspace, newest first.

## getCreator

Wraps [`creator`](/api/v2/docs/queries/creator).

Look up a single creator (influencer) by id in the current workspace.

## getCompetitorBrands

Wraps [`competitorBrands`](/api/v2/docs/queries/competitor-brands).

List Competitor Insights brands tracked for the current workspace, newest first, with aggregate metrics over a period/date window, so self-vs-competitor Share of Voice is computable in one call.

## getCompetitorBrand

Wraps [`competitorBrand`](/api/v2/docs/queries/competitor-brand).

Look up a single Competitor Insights brand by id in the current workspace, with aggregate metrics over a period/date window. Also resolves the workspace's own brand by its stable id (isOwnBrand: true).

## getCompetitorBrandItems

Wraps [`competitorBrandItems`](/api/v2/docs/queries/competitor-brand-items).

Paginate posts attributed to a single tracked Competitor Insights brand within a required `takenAt` time window.

## getCustomAttributeSchemas

Wraps [`customAttributeSchemas`](/api/v2/docs/queries/custom-attribute-schemas).

List custom attribute schemas for the current workspace, used both to INTERPRET values in the `customAttributes` JSON field on items/creators AND to BUILD `customAttributeConditions` filters for searchItems / searchCreators.

## getMediaContents

Wraps [`mediaContents`](/api/v2/docs/queries/media-contents).

Retrieve media contents (images / videos) for shop items OR for tracked Competitor Insights items in the current workspace.

## getTranscriptions

Wraps [`transcriptions`](/api/v2/docs/queries/transcriptions).

Fetch transcriptions for the media contents of one or more shop items in the current workspace.

## getCampaigns

Wraps [`campaigns`](/api/v2/docs/queries/campaigns).

List campaigns for the current workspace, newest first.

## getOperations

Wraps [`operations`](/api/v2/docs/queries/operations).

List operations for the current workspace, newest first. Only `refetch_engagement` operation type is listed here; an operation id visible via getOperation may be absent from this list if it is of another internal type.

## getEngagementHistory

Wraps [`engagementHistory`](/api/v2/docs/queries/engagement-history).

Paginated history of engagement metric snapshots for a single item, newest first.

## getWorkspace

Wraps [`workspace`](/api/v2/docs/queries/workspace).

Get a workspace — its tracked hashtags/mentions/keywords and connected social integrations — in one call. The workspace is selected by the optional `workspaceId` argument (falling back to the `WORKSPACE-ID` header, or your sole workspace when you can access exactly one). Call getWorkspaces first to discover the ids you can access.

## getWorkspaces

**no workspace**

Wraps [`workspaces`](/api/v2/docs/queries/workspaces).

List all workspaces the authenticated caller can access, newest first.

## getSocialProfile

**external call**

Wraps [`socialProfile`](/api/v2/docs/queries/social-profile).

Look up ONE social profile (influencer) in the current workspace. For MANY profiles do NOT loop this per id — call getSocialProfiles once to list/filter a whole page of profiles in a single call (the batch path).

## getSocialProfiles

Wraps [`socialProfiles`](/api/v2/docs/queries/social-profiles).

List social profiles (Instagram / TikTok / YouTube accounts) tracked for the current workspace, profiles with the most recent content first. This is the batch / multi-profile path — reach for it instead of calling getSocialProfile once per id when you need more than one profile.

## getContentViews

Wraps [`contentViews`](/api/v2/docs/queries/content-views).

List saved content (media deck) views for the current workspace, ordered most-recently-updated first.

## getContentView

Wraps [`contentView`](/api/v2/docs/queries/content-view).

Look up a single saved content (media deck) view by id in the current workspace.

## getOperation

Wraps [`operation`](/api/v2/docs/queries/operation).

Look up a single async operation by id in the current workspace — poll its status and progress (e.g. after refetchEngagementBulk).

## getOperationRecords

Wraps [`operationRecords`](/api/v2/docs/queries/operation-records).

Page through the per-item records of one operation, newest first — the follow-up to getOperation when itemIdsTruncated is true, and the way to enumerate an operation's items with their per-item status.

## getFilterPresets

**deprecated**

Wraps [`filterPresets`](/api/v2/docs/queries/filter-presets).

DEPRECATED — prefer the typed view tools getContentViews (accessor MEDIA_DECK) and getCollections (accessor COLLECTIONS); their ids work the same way as a presetId input. This tool still lists saved filter presets for the current workspace (no removal window announced), but new integrations should not adopt it. Use the returned id as `presetId:` when calling items(...) to scope a search to the preset's saved filter set.

**Deprecated** — Use contentViews / socialProfileViews / creatorViews / campaignCreatorViews / collections instead.

## getSocialProfileViews

Wraps [`socialProfileViews`](/api/v2/docs/queries/social-profile-views).

List saved Social Profile views for the current workspace, ordered most-recently-updated first.

## getSocialProfileView

Wraps [`socialProfileView`](/api/v2/docs/queries/social-profile-view).

Look up a single saved Social Profile view by id in the current workspace.

## getCreatorViews

Wraps [`creatorViews`](/api/v2/docs/queries/creator-views).

List saved Creator Views for the current workspace, ordered most-recently-updated first.

## getCreatorView

Wraps [`creatorView`](/api/v2/docs/queries/creator-view).

Look up a single saved Creator View by id in the current workspace.

## getViewGroups

Wraps [`viewGroups`](/api/v2/docs/queries/view-groups).

List user-created view groups for the current workspace, ordered oldest-first.

## getViewGroup

Wraps [`viewGroup`](/api/v2/docs/queries/view-group).

Look up a single user-created view group by id in the current workspace, including its member views.

## getCollections

Wraps [`collections`](/api/v2/docs/queries/collections).

List Collections (saved tag sets) for the current workspace, in the workspace's saved display order.

## getCollection

Wraps [`collection`](/api/v2/docs/queries/collection).

Look up a single Collection (saved tag set) by id in the current workspace.

## getItemIdsByUrl

Wraps [`itemIdsByUrl`](/api/v2/docs/queries/item-ids-by-url).

Resolve public social-media post URLs to shop-item UUIDs in the current workspace.

## getWebhookSubscriptions

Wraps [`webhookSubscriptionsConnection`](/api/v2/docs/queries/webhook-subscriptions-connection).

List outbound-webhook subscriptions for the current workspace, newest first. The id-resolution source for updateWebhookSubscription / deleteWebhookSubscription / rotateWebhookSubscriptionSecret / sendWebhookTestEvent / enableWebhookSubscription — resolve subscription ids here, never guess.

## getWebhookDeliveries

Wraps [`webhookDeliveries`](/api/v2/docs/queries/webhook-deliveries).

Paginate webhook deliveries (the dead-letter / observability surface) for the current workspace, newest first. THE source for redeliverWebhookDelivery's required `deliveryId` — filter by status "FAILED" and pick the delivery's `id`; never guess ids.

## getWebhookEvents

Wraps [`webhookEvents`](/api/v2/docs/queries/webhook-events).

Paginate webhook events (the outbox — the Stripe /v1/events pattern) for the current workspace, newest first. The reconciliation surface: query it to recover business events whose deliveries were DROPPED or missed; an event's `id` doubles as its idempotency key.