# Queries

Read operations exposed by the Archive GraphQL API, grouped by functional area.

## Workspaces

- [`workspace`](/api/v2/docs/queries/workspace) — Return details for the current workspace, inferred from the WORKSPACE-ID header.
- [`workspaces`](/api/v2/docs/queries/workspaces) — List all workspaces that the current API user has access to.

## Items & Media

- [`itemIdsByUrl`](/api/v2/docs/queries/item-ids-by-url) — Look up item IDs by social media URLs within the current workspace. Accepts any public HTTP(S) URL. INVALID_URL is returned only for malformed / non-HTTP URLs or private/reserved hosts; a valid public URL we cannot resolve (unrecognized shape, short link, or no matching item) returns NOT_FOUND. Recognized shapes (non-exhaustive hint): Instagram (/p/, /reel/, /reels/), TikTok (@user/video/{id}, @user/photo/{id}), and YouTube (/shorts/, /watch?v=, youtu.be/).
- [`items`](/api/v2/docs/queries/items) — Search and paginate archived items (social content) for the current workspace.
- [`mediaContents`](/api/v2/docs/queries/media-contents) — Retrieve media contents (images / videos) for shop items (`itemIds`) or for `CompetitorBrandItem` rows (`competitorBrandItemIds`). Pass exactly one. See the resolver description for routing details.
- [`transcriptions`](/api/v2/docs/queries/transcriptions) — Fetch transcriptions for one or more media contents belonging to the current workspace.

## Creators & Social Profiles

- [`creator`](/api/v2/docs/queries/creator) — Return details for the creator.
- [`creators`](/api/v2/docs/queries/creators) — List and paginate creators for the current workspace, ordered newest first.
- [`socialProfile`](/api/v2/docs/queries/social-profile) — Return details for a social profile by ID or account identifier.
- [`socialProfiles`](/api/v2/docs/queries/social-profiles) — List and paginate social profiles for the current workspace. Pass `presetId` (a Social Profile View id from `socialProfileViews` / `socialProfileView`) to drive results off the view's stored conditions and sort; otherwise narrow with `filter`.

## Engagement

- [`engagementHistory`](/api/v2/docs/queries/engagement-history) — Paginated history of engagement metric snapshots for a specific item, ordered newest first.

## Campaigns

- [`campaigns`](/api/v2/docs/queries/campaigns) — List and paginate campaigns for the current workspace, ordered newest first. Workflow-type rows are excluded to match the in-app CRM listing.

## Competitor Insights

- [`competitorBrand`](/api/v2/docs/queries/competitor-brand) — Return a single Competitor Insights brand by ID for the current workspace, or null if no brand with that ID is tracked here. Also resolves the workspace's own-brand entry by its stable id. Pair with `competitorBrandItems(brandId:, filter:, …)` to paginate the brand's media items. If aggregate metrics are unavailable, roster data remains and the response includes a `SERVICE_UNAVAILABLE` error; match on `extensions.code` and retry later.
- [`competitorBrandItems`](/api/v2/docs/queries/competitor-brand-items) — Paginate Competitor Insights posts for a brand within a required `filter.takenAt` window. Posts for a given month become queryable on day 9 of the following month.
- [`competitorBrands`](/api/v2/docs/queries/competitor-brands) — List Competitor Insights brands tracked by the current workspace, ordered newest first, with aggregate metrics over a `period`/`date` window (default month). The workspace's own-brand entry is returned as one additional pinned node on the first page (flagged `isOwnBrand`), in addition to up to `first` competitor brands, so self-vs-competitor Share of Voice is computable in-query; `totalCount` counts tracked competitor brands only. Pair with `competitorBrandItems(brandId:, filter:, …)` to paginate a brand's media items. If aggregate metrics are unavailable, roster data remains and the response includes a `SERVICE_UNAVAILABLE` error; match on `extensions.code` and retry later.

## Collections

- [`collection`](/api/v2/docs/queries/collection) — Return a single Collection by ID for the current workspace, or null if no such Collection exists here.
- [`collections`](/api/v2/docs/queries/collections) — List Collections (saved tag sets) for the current workspace, in the workspace's saved order. Returns at most 1000 rows; this field is not paginated.

## Views & View Groups

- [`contentView`](/api/v2/docs/queries/content-view) — Return a single saved content (media deck) view by ID for the current workspace, or null if no such view exists here. Pair with `items(presetId:)` to fetch the items belonging to a view.
- [`contentViews`](/api/v2/docs/queries/content-views) — List saved content (media deck) views for the current workspace, ordered by most-recently-updated first. Pair with `items(presetId:)` to fetch the items belonging to a view. Returns at most 1000 rows; this field is not paginated.
- [`creatorView`](/api/v2/docs/queries/creator-view) — Return a single saved Creator View by ID for the current workspace, or null if no such view exists here. Pair with `creators(presetId:)` to fetch the creators belonging to a view.
- [`creatorViews`](/api/v2/docs/queries/creator-views) — List saved Creator Views for the current workspace, ordered by most-recently-updated first. Pair with `creators(presetId:)` to fetch the creators belonging to a view. Returns at most 1000 rows; this field is not paginated.
- [`socialProfileView`](/api/v2/docs/queries/social-profile-view) — Return a single saved Social Profile view by ID for the current workspace, or null if no such view exists here.
- [`socialProfileViews`](/api/v2/docs/queries/social-profile-views) — List saved Social Profile views for the current workspace, ordered by most-recently-updated first. Returns at most 1000 rows; this field is not paginated.
- [`viewGroup`](/api/v2/docs/queries/view-group) — Return a single user-created view group by ID for the current workspace, or null if no such group exists here.
- [`viewGroups`](/api/v2/docs/queries/view-groups) — List user-created view groups for the current workspace, ordered oldest-first. Returns at most 1000 rows; this field is not paginated.

## Custom Attributes

- [`customAttributeSchemas`](/api/v2/docs/queries/custom-attribute-schemas) — Retrieve custom attribute schemas to interpret customAttributes values. Returns at most 1000 rows; this field is not paginated.

## Filtering

- [`filterPresets`](/api/v2/docs/queries/filter-presets) (deprecated) — List saved filter presets for items queries in the current workspace. Returns at most 1000 rows; this field is not paginated.

## Async Operations

- [`operation`](/api/v2/docs/queries/operation) — Return details for an operation by ID, including status and progress.
- [`operationRecords`](/api/v2/docs/queries/operation-records) — Paginate the per-item records of an operation, newest first. Optionally filter by record status.
- [`operations`](/api/v2/docs/queries/operations) — List operations for the current workspace, ordered newest first.

## Webhooks

- [`webhookDeliveries`](/api/v2/docs/queries/webhook-deliveries) — Paginate webhook deliveries (dead-letter surface) for the current workspace, newest first. Filter by subscription and/or status. History is retained for 30 days.
- [`webhookEvents`](/api/v2/docs/queries/webhook-events) — Paginate webhook events (the outbox) for the current workspace, newest first. Filter by event type. History is retained for 30 days.
- [`webhookSubscriptions`](/api/v2/docs/queries/webhook-subscriptions) — List outbound-webhook subscriptions for the current workspace, newest first. Returns at most 1000 rows; this field is not paginated.
- [`webhookSubscriptionsConnection`](/api/v2/docs/queries/webhook-subscriptions-connection) — Cursor-paginated variant of webhookSubscriptions: list outbound-webhook subscriptions for the current workspace, newest first.