API reference

This page lists every query and mutation in SocialScope's consumer GraphQL API, with arguments, return fields, rules, errors and a server-side example. The machine-readable schema is at /schema.graphql. All operations except status need your application key. Every call is a POST with a JSON body holding one operation.

Endpoint

POST /graphql
Content-Type: application/json
Authorization: Bearer <key-id>.<secret>

{"query": "...", "variables": {...}}

Limits per request: one operation, no batching, 8 aliases, depth 8, cost 100 (each root field 10, each nested field 1), 64 KiB body. Limit, validation and batching errors return HTTP 400 with BAD_USER_INPUT. An oversized body returns HTTP 413 with no GraphQL body. See Authentication.

Calling from TypeScript

Every example below uses this server-only helper.

// lib/socialscope.ts
// Server only. Never import this file from browser code.
const TIMEOUT_MS = 10_000; // 10 s

export class SocialScopeError extends Error {
  constructor(
    readonly code: string,
    readonly correlationId?: string,
    readonly retryAfterSeconds?: number,
  ) {
    super(code);
    this.name = "SocialScopeError";
  }
}

type GraphQLResponse<T> = {
  data?: T;
  errors?: {
    message: string;
    extensions?: { code?: string; correlationId?: string; retryAfterSeconds?: number };
  }[];
};

export async function socialscope<T>(query: string, variables: Record<string, unknown> = {}): Promise<T> {
  const url = process.env.SOCIALSCOPE_GRAPHQL_URL;
  const key = process.env.SOCIALSCOPE_CONSUMER_KEY;
  if (!url || !key) throw new SocialScopeError("SOCIALSCOPE_NOT_CONFIGURED");

  let response: Response;
  try {
    response = await fetch(url, {
      method: "POST",
      cache: "no-store", // never let a framework cache a SocialScope response
      signal: AbortSignal.timeout(TIMEOUT_MS),
      headers: { "content-type": "application/json", authorization: `Bearer ${key}` },
      body: JSON.stringify({ query, variables }),
    });
  } catch {
    // Network failure or timeout. Never log the request: it carries the key.
    throw new SocialScopeError("SOCIALSCOPE_UNAVAILABLE");
  }

  // A body over 64 KiB is refused with HTTP 413 before GraphQL runs, so there is no GraphQL error body.
  if (response.status === 413) throw new SocialScopeError("SOCIALSCOPE_REQUEST_TOO_LARGE");

  // Errors arrive with HTTP 200, or 400 for validation, limit and batching errors. Read the body either way.
  const payload = (await response.json().catch(() => null)) as GraphQLResponse<T> | null;
  const first = payload?.errors?.[0];
  if (first) {
    throw new SocialScopeError(first.extensions?.code ?? "UPSTREAM_UNAVAILABLE", first.extensions?.correlationId, first.extensions?.retryAfterSeconds);
  }
  if (!response.ok || !payload?.data) throw new SocialScopeError("SOCIALSCOPE_UNAVAILABLE");
  return payload.data;
}

export type Scope = { tenantKey: string; externalSubjectId: string };

In the examples, scope is always built on the server from the signed-in session:

const scope = { tenantKey: session.tenantKey, externalSubjectId: session.userId };

Queries

status

Unauthenticated liveness check.

query Status {
  status {
    ok
    message
  }
}

Returns ApiStatus { ok: Boolean!, message: String! }.

curl -sS -X POST https://connect.socialscope.hardscope.incdev.dev/graphql \
  -H 'content-type: application/json' \
  -d '{"query":"query Status { status { ok message } }"}'

integrationReadiness

What your app can offer right now.

query IntegrationReadiness {
  integrationReadiness {
    providers {
      provider
      available
    }
    googleIdentityAvailable
  }
}

true is a configuration check, not proof a live consent will succeed. false or an error means show the action as unavailable.

curl -sS -X POST "$SOCIALSCOPE_GRAPHQL_URL" \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $SOCIALSCOPE_CONSUMER_KEY" \
  -d '{"query":"query IntegrationReadiness { integrationReadiness { providers { provider available } googleIdentityAvailable } }"}'

connectSessionResult(scope, id)

The outcome of one Connect attempt.

Returns ConnectSessionResult:

An unfinished attempt read after its 10-minute deadline returns EXPIRED. After resultExpiresAt the read returns NOT_FOUND. A tenant that is not registered for your app returns FORBIDDEN.

const { connectSessionResult } = await socialscope<{ connectSessionResult: { status: string; connectionId: string | null } }>(
  `query VerifyConnection($scope: SubjectScope!, $id: ID!) {
    connectSessionResult(scope: $scope, id: $id) { id provider status resultCode connectionId creatorAction expiresAt resultExpiresAt }
  }`,
  { scope, id: savedAttemptId },
);

connection(scope, id)

One connection's current state.

Returns Connection:

Profile fields: providerAccountId, displayName, handle, avatarUrl, profileUrl, description, observedAt.

SocialScope rechecks a CONNECTED connection on every read. Instead of returning the row, connection throws AUTHORIZATION_SUSPENDED when the provider registration is paused, RECONNECT_REQUIRED when the grant is no longer active or its refresh credential expired, CAPABILITY_UNAVAILABLE when the registration no longer serves your app, and FORBIDDEN when your app's policy no longer allows the tenant, provider or capability. Map each code to that account's state. Other statuses return the row with a null profile. An erased or foreign connection returns NOT_FOUND.

const { connection } = await socialscope<{ connection: { id: string; status: string; syncStatus: string } }>(
  `query ReadConnection($scope: SubjectScope!, $id: ID!) {
    connection(scope: $scope, id: $id) {
      id provider providerAccountId status syncStatus lastSuccessfulSyncAt nextRetryAt
      capabilities { capability availability reason }
      profile { displayName handle avatarUrl profileUrl description observedAt }
    }
  }`,
  { scope, id: connectionId },
);

connections(scope, first, after)

The subject's connections in this tenant.

Returns ConnectionPage { items: [Connection!]!, pageInfo: ConnectionPageInfo! }, where ConnectionPageInfo is { endCursor: String, hasNextPage: Boolean! }. Includes connections in every status until a disconnected one is erased. Each row goes through the same check as connection, so one account that fails it makes the whole call fail with that account's code. Keep connection IDs in your own database and read them with connection, using this list as a convenience.

const { connections } = await socialscope<{
  connections: { items: { id: string; provider: string; status: string }[]; pageInfo: { endCursor: string | null; hasNextPage: boolean } };
}>(
  `query ListConnections($scope: SubjectScope!, $first: Int, $after: String) {
    connections(scope: $scope, first: $first, after: $after) {
      items { id provider status syncStatus profile { displayName handle avatarUrl observedAt } }
      pageInfo { endCursor hasNextPage }
    }
  }`,
  { scope, first: 100 },
);

content(scope, connectionId, window)

Stored posts published in a window, newest first. Needs CONTENT_LIST.

Returns ContentPage:

ContentItem fields:

MetricObservation fields: name (VIEWS, LIKES, COMMENTS, SHARES), value (DecimalCount, an integer string or null), availability, reason, sourceField, observedAt.

const { content } = await socialscope<{ content: { items: unknown[]; pageInfo: { completeForWindow: boolean } } }>(
  `query ReadContent($scope: SubjectScope!, $connectionId: ID!, $window: ContentWindow!) {
    content(scope: $scope, connectionId: $connectionId, window: $window) {
      items {
        id providerContentId provider kind canonicalUrl thumbnailUrl title description publishedAt
        availability reason observedAt
        metrics { name value availability reason sourceField observedAt }
      }
      pageInfo { endCursor hasNextPage completeForWindow incompleteReason }
      lastSuccessfulSyncAt
    }
  }`,
  {
    scope,
    connectionId,
    window: { publishedAfter: "2026-09-01T00:00:00Z", publishedBefore: "2026-10-01T00:00:00Z", first: 50 },
  },
);

contentItem(scope, connectionId, providerContentId)

One stored post. Needs CONTENT_LIST or CONTENT_LOOKUP.

Returns ContentItem or null when never observed. A post last observed more than 30 days ago returns with fields null, availability: UNAVAILABLE, reason: EXPIRED and no metrics.

const { contentItem } = await socialscope<{ contentItem: { providerContentId: string } | null }>(
  `query ReadPost($scope: SubjectScope!, $connectionId: ID!, $providerContentId: String!) {
    contentItem(scope: $scope, connectionId: $connectionId, providerContentId: $providerContentId) {
      providerContentId kind canonicalUrl title description publishedAt availability reason observedAt
      metrics { name value availability reason sourceField observedAt }
    }
  }`,
  { scope, connectionId, providerContentId },
);

syncJob(scope, connectionId, id)

The state of a refresh, metrics, lookup, revoke or erase job.

Returns SyncJob:

Finished jobs are readable for 7 days. Revoke and erase receipts are readable for 7 days after creation, even after the connection is erased.

const { syncJob } = await socialscope<{ syncJob: { status: string; errorCode: string | null } }>(
  `query ReadJob($scope: SubjectScope!, $connectionId: ID!, $id: ID!) {
    syncJob(scope: $scope, connectionId: $connectionId, id: $id) {
      id status nextRetryAt errorCode creatorAction resultProviderContentId
      completeForWindow incompleteReason continuationCursor
    }
  }`,
  { scope, connectionId, id: jobId },
);

Mutations

createConnectSession(input)

Start a Connect attempt. See Connect.

ConnectInput:

Returns ConnectSession:

Errors: FORBIDDEN, BAD_USER_INPUT, NOT_FOUND (reconnect target), RECONNECT_REQUIRED (the target changed state during creation, rare), DISCONNECT_IN_PROGRESS, RATE_LIMITED (5 unfinished attempts per subject and provider). In production FORBIDDEN is also returned for a while after a YouTube or TikTok disconnect, until its revoke settles. Retry later.

const { createConnectSession } = await socialscope<{
  createConnectSession: { id: string; launchUrl: string; launchToken: string; expiresAt: string; resultExpiresAt: string };
}>(
  `mutation StartConnection($input: ConnectInput!) {
    createConnectSession(input: $input) { id launchUrl launchToken expiresAt resultExpiresAt }
  }`,
  {
    input: {
      scope,
      provider: "INSTAGRAM",
      capabilities: ["PROFILE", "CONTENT_LIST", "CONTENT_METRICS"],
      returnUrl: "https://app.example.com/social/return",
    },
  },
);

disconnectConnection(scope, connectionId)

Stop access at once and start the upstream revoke and the erase. Idempotent until erasure. In production, a YouTube or TikTok disconnect also suspends other accounts on that provider until the revoke settles. See Connect.

Returns DisconnectResult:

A second call before erasure returns the same job IDs. After erasure it returns NOT_FOUND.

const { disconnectConnection } = await socialscope<{
  disconnectConnection: { accepted: boolean; connectionId: string; revokeJobId: string; eraseJobId: string };
}>(
  `mutation Disconnect($scope: SubjectScope!, $connectionId: ID!) {
    disconnectConnection(scope: $scope, connectionId: $connectionId) {
      accepted connectionId upstreamRevocationPending revokeJobId eraseJobId
    }
  }`,
  { scope, connectionId },
);

requestRefresh(scope, connectionId, providerContentId, window, continuationCursor)

Queue a scan of a window, or a metrics refresh of one stored post. Returns a SyncJob.

A scan needs CONTENT_LIST. The same window or post while one is in flight returns the existing job. A different window while a scan is in flight fails with SYNC_WINDOW_BUSY. More than 20 in-flight read jobs for your app fail with RATE_LIMITED (retryAfterSeconds: 60).

const { requestRefresh } = await socialscope<{ requestRefresh: { id: string; status: string } }>(
  `mutation RefreshWindow($scope: SubjectScope!, $connectionId: ID!, $window: SyncWindow) {
    requestRefresh(scope: $scope, connectionId: $connectionId, window: $window) { id status }
  }`,
  {
    scope,
    connectionId,
    window: { publishedAfter: "2026-09-05T00:00:00Z", publishedBefore: "2026-10-05T00:00:00Z", maxItems: 100 },
  },
);

requestContentLookup(scope, connectionId, url)

Resolve a post URL to an owned post and observe it. Needs CONTENT_LOOKUP. Returns a SyncJob. Poll it and read resultProviderContentId, then read contentItem and check its availability. A lookup can succeed and still leave the post UNAVAILABLE, with the reason in incompleteReason.

const { requestContentLookup } = await socialscope<{ requestContentLookup: { id: string } }>(
  `mutation Lookup($scope: SubjectScope!, $connectionId: ID!, $url: String!) {
    requestContentLookup(scope: $scope, connectionId: $connectionId, url: $url) { id status }
  }`,
  { scope, connectionId, url: "https://www.youtube.com/watch?v=abcdefghijk" },
);

createGoogleIdentitySession(input)

Start a Google sign-in handoff. See Google identity.

GoogleIdentityInput: tenantKey: String! (registered for your app), returnUrl: String! (your exactly registered identity return URL).

Returns GoogleIdentitySession:

Errors: CAPABILITY_UNAVAILABLE, FORBIDDEN, BAD_USER_INPUT, RATE_LIMITED with retryAfterSeconds (20 unfinished attempts per app).

const { createGoogleIdentitySession } = await socialscope<{
  createGoogleIdentitySession: { id: string; launchUrl: string; launchToken: string; resultProof: string };
}>(
  `mutation StartGoogleIdentity($input: GoogleIdentityInput!) {
    createGoogleIdentitySession(input: $input) { id launchUrl launchToken resultProof expiresAt resultExpiresAt }
  }`,
  { input: { tenantKey: "example-workspace", returnUrl: "https://app.example.com/auth/google/return" } },
);

redeemGoogleIdentityResult(id, tenantKey, resultProof)

Redeem the identity result once.

Returns GoogleIdentityResult:

PENDING does not consume the proof. Every other status does. A second redeem returns NOT_FOUND.

const { redeemGoogleIdentityResult } = await socialscope<{
  redeemGoogleIdentityResult: { status: string; issuer: string | null; googleSub: string | null };
}>(
  `mutation RedeemGoogleIdentity($id: ID!, $tenantKey: String!, $resultProof: String!) {
    redeemGoogleIdentityResult(id: $id, tenantKey: $tenantKey, resultProof: $resultProof) {
      status issuer googleSub email emailVerified name pictureUrl
    }
  }`,
  { id: saved.id, tenantKey: saved.tenantKey, resultProof: saved.resultProof },
);

Shared types

Every code a consumer can see is listed in Errors.