Type definitions

Copy-pasteable TypeScript helpers for common Xquik API objects. Use these for prototypes, docs examples, and lightweight clients. For complete generated coverage, use the OpenAPI spec or an official SDK.

Usage

3 ways to use these types in your project:

Copy curated types - copy the “Response types”, “Request types”, and “Shared types” tabs into a single xquik-types.ts file
Copy individual interfaces - grab only the types you need (e.g. Tweet, EventList)
Generate full coverage from OpenAPI - use the OpenAPI spec with tools like openapi-typescript to auto-generate types:
npx openapi-typescript https://docs.xquik.com/openapi.yaml -o xquik-api.d.ts

For production projects, option 3 or an official SDK is the safest source for complete coverage. For quick prototypes, copy only the interfaces you need.

Response types
Request types
Shared types

Response objects returned by API endpoints.

// ─── Account ─────────────────────────────────────────────

interface Account {
  plan: "active" | "inactive";
  monitorsAllowed: number;
  monitorsUsed: number;
  creditInfo?: {
    balance: number;
    lifetimePurchased: number;
    lifetimeUsed: number;
    autoTopupEnabled: boolean;
  };
  xUsername?: string;
}

// ─── API Keys ────────────────────────────────────────────

// Returned when creating a new key (includes full key)
interface ApiKeyCreated {
  id: string;
  fullKey: string;
  prefix: string;
  name: string;
  createdAt: string;
}

// Returned when listing keys (full key is never exposed)
interface ApiKey {
  id: string;
  name: string;
  prefix: string;
  isActive: boolean;
  createdAt: string;
  lastUsedAt?: string;
}

// ─── Monitors ────────────────────────────────────────────

interface Monitor {
  id: string;
  username: string;
  xUserId: string;
  eventTypes: EventType[];
  isActive: boolean;
  createdAt: string;
  nextBillingAt: string;
}

interface KeywordMonitor {
  id: string;
  query: string;
  eventTypes: EventType[];
  isActive: boolean;
  createdAt: string;
  nextBillingAt: string;
}

// ─── Events ──────────────────────────────────────────────

interface Event {
  id: string;
  type: EventType;
  monitorId: string;
  monitorType: "account" | "keyword";
  occurredAt: string;
  data: EventData;
  username?: string;
  query?: string;
  keywordMonitorId?: string;
  xEventId?: string;
}

interface EventList {
  events: Event[];
  hasMore: boolean;
  nextCursor?: string;
}

// ─── Webhooks ────────────────────────────────────────────

// Returned when creating a webhook (includes signing secret)
interface WebhookCreated {
  id: string;
  url: string;
  eventTypes: EventType[];
  secret: string;
  createdAt: string;
}

// Returned when listing webhooks (secret is never exposed)
interface Webhook {
  id: string;
  url: string;
  eventTypes: EventType[];
  isActive: boolean;
  createdAt: string;
}

// ─── Deliveries ──────────────────────────────────────────

interface Delivery {
  id: string;
  streamEventId: string;
  status: "pending" | "delivered" | "failed" | "exhausted";
  attempts: number;
  lastStatusCode?: number;
  lastError?: string;
  createdAt: string;
  deliveredAt?: string;
}

// ─── Webhook Payload ─────────────────────────────────────

interface WebhookPayload {
  eventType: EventType;
  schemaVersion: 1;
  deliveryId: string;
  streamEventId: string;
  occurredAt: string;
  data: EventData;
  username?: string;
  query?: string;
}

interface WebhookTestPayload {
  eventType: "webhook.test";
  data: { message: string };
  timestamp: string;
}

// ─── Draws ──────────────────────────────────────────────

interface Draw {
  id: string;
  tweetId: string;
  tweetUrl: string;
  tweetText: string;
  tweetAuthorUsername: string;
  tweetLikeCount: number;
  tweetRetweetCount: number;
  tweetReplyCount: number;
  tweetQuoteCount: number;
  status: "pending" | "running" | "completed" | "failed";
  totalEntries: number;
  validEntries: number;
  createdAt: string;
  drawnAt?: string;
}

interface DrawListItem {
  id: string;
  tweetUrl: string;
  status: "pending" | "running" | "completed" | "failed";
  totalEntries: number;
  validEntries: number;
  createdAt: string;
  drawnAt?: string;
}

interface DrawWinner {
  position: number;
  authorUsername: string;
  tweetId: string;
  isBackup: boolean;
}

interface DrawList {
  draws: DrawListItem[];
  hasMore: boolean;
  nextCursor?: string;
}

// ─── Extractions ────────────────────────────────────────

interface ExtractionJob {
  id: string;
  toolType: ExtractionToolType;
  status: "pending" | "running" | "completed" | "failed";
  totalResults: number;
  targetTweetId?: string;
  targetUsername?: string;
  targetUserId?: string;
  targetCommunityId?: string;
  searchQuery?: string;
  errorMessage?: string;
  createdAt: string;
  completedAt?: string;
}

interface ExtractionResult {
  id: string;
  xUserId: string;
  xUsername?: string;
  xDisplayName?: string;
  xFollowersCount?: number;
  xVerified?: boolean;
  xProfileImageUrl?: string;
  tweetId?: string;
  tweetText?: string;
  tweetCreatedAt?: string;
  createdAt: string;
  enrichmentData?: Record<string, unknown>;
}

interface ExtractionList {
  extractions: ExtractionJob[];
  hasMore: boolean;
  nextCursor?: string;
}

interface ExtractionEstimate {
  allowed: boolean;
  source: "replyCount" | "retweetCount" | "quoteCount" | "followers" | "resultsLimit" | "unknown";
  estimatedResults: number;
  creditsRequired: string;
  creditsAvailable: string;
  resolvedXUserId?: string;
}

// ─── X API ──────────────────────────────────────────────

interface Tweet {
  id: string;
  text: string;
  type?: string;
  createdAt?: string;
  retweetCount?: number;
  replyCount?: number;
  likeCount?: number;
  quoteCount?: number;
  viewCount?: number;
  bookmarkCount?: number;
  media?: TweetMediaItem[];
  url?: string;
  lang?: string;
  isReply?: boolean;
  inReplyToId?: string;
  inReplyToUserId?: string;
  inReplyToUsername?: string;
  conversationId?: string;
  source?: string;
  displayTextRange?: number[];
  isNoteTweet?: boolean;
  isQuoteStatus?: boolean;
  isLimitedReply?: boolean;
  entities?: Record<string, unknown>;
  author?: UserProfile;
  quoted_tweet?: Tweet;
  retweeted_tweet?: Tweet;
}

interface TweetAuthor {
  id: string;
  username: string;
  followers: number;
  verified: boolean;
  profilePicture?: string;
}

interface TweetSearchResult {
  id: string;
  text: string;
  createdAt: string;
  likeCount: number;
  retweetCount: number;
  replyCount: number;
  author: {
    id: string;
    username: string;
    name: string;
    verified: boolean;
  };
  media?: TweetMediaItem[];
}

interface UserProfile {
  id: string;
  username: string;
  name: string;
  description?: string;
  followers?: number;
  following?: number;
  verified?: boolean;
  profilePicture?: string;
  coverPicture?: string;
  location?: string;
  createdAt?: string;
  statusesCount?: number;
  mediaCount?: number;
  canDm?: boolean;
  url?: string;
  favouritesCount?: number;
  hasCustomTimelines?: boolean;
  isTranslator?: boolean;
  withheldInCountries?: string[];
  possiblySensitive?: boolean;
  pinnedTweetIds?: string[];
  isAutomated?: boolean;
  automatedBy?: string;
  unavailable?: boolean;
  unavailableReason?: string;
  verifiedType?: string;
  profile_bio?: Record<string, unknown>;
}

interface FollowerCheck {
  sourceUsername: string;
  targetUsername: string;
  isFollowing: boolean;
  isFollowedBy: boolean;
}

// ─── Trends ─────────────────────────────────────────────

interface Trend {
  name: string;
  description?: string;
  rank?: number;
  query?: string;
}

interface TrendList {
  trends: Trend[];
  total: number;
  woeid: number;
}

// ─── Radar ──────────────────────────────────────────────

interface RadarItem {
  id: string;
  title: string;
  description?: string;
  url?: string;
  imageUrl?: string;
  source: RadarSource;
  sourceId: string;
  category: RadarCategory;
  region: string;
  language: string;
  score: number;
  metadata: Record<string, unknown>;
  publishedAt: string;
  createdAt: string;
}

interface RadarList {
  items: RadarItem[];
  hasMore: boolean;
  nextCursor?: string;
}

// ─── Styles ─────────────────────────────────────────────

interface StyleProfile {
  xUsername: string;
  isOwnAccount: boolean;
  tweetCount: number;
  fetchedAt: string;
  tweets: StyleTweet[];
}

interface StyleListItem {
  xUsername: string;
  isOwnAccount: boolean;
  tweetCount: number;
  fetchedAt: string;
}

interface StyleList {
  styles: StyleListItem[];
}

interface StyleComparison {
  style1: StyleProfile;
  style2: StyleProfile;
}

interface PerformanceAnalysis {
  xUsername: string;
  tweetCount: number;
  tweets: PerformanceTweet[];
}

// ─── Drafts ─────────────────────────────────────────────

interface Draft {
  id: string;
  text: string;
  topic?: string;
  goal?: "engagement" | "followers" | "authority" | "conversation";
  createdAt: string;
  updatedAt: string;
}

interface DraftList {
  drafts: Draft[];
  hasMore: boolean;
  nextCursor?: string;
}

// ─── X Accounts ───────────────────────────────────────────

interface XAccount {
  id: string;
  username: string;
  displayName: string;
  isActive: boolean;
  createdAt: string;
}

// ─── Compose ──────────────────────────────────────────────

// step="compose" response
interface ComposeTweetResult {
  contentRules: { rule: string }[];
  engagementMultipliers: { action: string; multiplier: string }[];
  engagementVelocity: string;
  followUpQuestions: string[];
  intentUrl: string;
  nextStep: string;
  savedStyles?: { tweetCount: number; username: string }[];
  scorerWeights: { signal: string; weight: number; context: string }[];
  source: string;
  styleNote?: string;
  styleTweets?: string[];
  topPenalties: string[];
}

// step="refine" response
interface RefineTweetResult {
  compositionGuidance: string[];
  examplePatterns: { description: string; pattern: string }[];
  intentUrl: string;
  nextStep: string;
}

// step="score" response
interface ScoreTweetResult {
  passed: boolean;
  passedCount: number;
  totalChecks: number;
  topSuggestion: string;
  nextStep: string;
  checklist: { factor: string; passed: boolean; suggestion?: string }[];
  intentUrl?: string;
}

// ─── X Write ──────────────────────────────────────────────

interface XWriteResponse {
  success: boolean;
  data?: Record<string, unknown>;
}

// ─── Support Tickets ──────────────────────────────────────

interface SupportTicket {
  publicId: string;
  subject: string;
  status: "open" | "in_progress" | "resolved" | "closed";
  messageCount: number;
  createdAt: string;
  updatedAt: string;
}

interface SupportTicketDetail {
  publicId: string;
  subject: string;
  status: "open" | "in_progress" | "resolved" | "closed";
  createdAt: string;
  updatedAt: string;
  messages: SupportMessage[];
}

interface SupportMessage {
  body: string;
  sender: "user" | "support";
  createdAt: string;
}

// ─── Error Response ──────────────────────────────────────

interface ApiError {
  error: string;
  limit?: number; // only present for monitor_limit_reached
}

Request body types for POST/PATCH endpoints.

interface CreateMonitorRequest {
  username: string;
  eventTypes: EventType[];
}

interface UpdateMonitorRequest {
  eventTypes?: EventType[];
  isActive?: boolean;
}

interface CreateWebhookRequest {
  url: string;
  eventTypes: EventType[];
}

interface UpdateWebhookRequest {
  url?: string;
  eventTypes?: EventType[];
  isActive?: boolean;
}

interface CreateApiKeyRequest {
  name?: string;
}

interface CreateDrawRequest {
  tweetUrl: string;
  winnerCount?: number;
  backupCount?: number;
  uniqueAuthorsOnly?: boolean;
  mustRetweet?: boolean;
  mustFollowUsername?: string;
  filterMinFollowers?: number;
  filterAccountAgeDays?: number;
  filterLanguage?: string;
  requiredKeywords?: string[];
  requiredHashtags?: string[];
  requiredMentions?: string[];
}

interface CreateExtractionRequest {
  toolType: ExtractionToolType;
  targetTweetId?: string;
  targetUsername?: string;
  targetCommunityId?: string;
  targetListId?: string;
  targetSpaceId?: string;
  searchQuery?: string;
  resultsLimit?: number;
}

interface CreateDraftRequest {
  text: string;
  topic?: string;
  goal?: "engagement" | "followers" | "authority" | "conversation";
}

interface ComposeRequest {
  step: "compose" | "refine" | "score";
  topic?: string;
  goal?: ComposeTweetGoal;
  styleUsername?: string;
  tone?: string;
  additionalContext?: string;
  callToAction?: string;
  hasLink?: boolean;
  hasMedia?: boolean;
  mediaType?: MediaType;
  draft?: string;
}

Enums and shared types used across request and response objects.

type EventType =
  | "tweet.new"
  | "tweet.quote"
  | "tweet.reply"
  | "tweet.retweet"
  | "tweet.media"
  | "tweet.link"
  | "tweet.poll"
  | "tweet.mention"
  | "tweet.hashtag"
  | "tweet.longform"
  | "profile.avatar.changed"
  | "profile.banner.changed"
  | "profile.name.changed"
  | "profile.username.changed"
  | "profile.bio.changed"
  | "profile.location.changed"
  | "profile.url.changed"
  | "profile.verified.changed"
  | "profile.protected.changed"
  | "profile.pinned_tweet.changed"
  | "profile.unavailable.changed";

// The data field contains the raw tweet object from the X real-time stream.
interface TweetEventData {
  id: string;
  text: string;
  author: {
    id: string;
    userName: string;
    name: string;
  };
  isRetweet: boolean;
  isReply: boolean;
  isQuote: boolean;
  createdAt: string;
  inReplyToId?: string;
  quoted_tweet?: {
    id: string;
    text: string;
    author: { userName: string };
  };
}

type EventData = TweetEventData;

interface EventFilters {
  keywords?: { include?: string[]; exclude?: string[] };
  minLikes?: number;
  minRetweets?: number;
  verifiedOnly?: boolean;
}

type ExtractionToolType =
  | "article_extractor"
  | "community_extractor"
  | "community_moderator_explorer"
  | "community_post_extractor"
  | "community_search"
  | "favoriters"
  | "follower_explorer"
  | "following_explorer"
  | "list_follower_explorer"
  | "list_member_extractor"
  | "list_post_extractor"
  | "mention_extractor"
  | "people_search"
  | "post_extractor"
  | "quote_extractor"
  | "reply_extractor"
  | "repost_extractor"
  | "space_explorer"
  | "thread_extractor"
  | "tweet_search_extractor"
  | "user_likes"
  | "user_media"
  | "verified_follower_explorer";

type ComposeTweetGoal = "authority" | "conversation" | "engagement" | "followers";
type MediaType = "none" | "photo" | "video";

type RadarSource = string;

type RadarCategory =
  | "business"
  | "culture"
  | "dev"
  | "entertainment"
  | "general"
  | "politics"
  | "science"
  | "tech";

interface TweetMediaItem {
  mediaUrl: string;
  type: string;
  url: string;
}

interface StyleTweet {
  id: string;
  authorUsername: string;
  text: string;
  createdAt: string;
  media?: TweetMediaItem[];
}

interface PerformanceTweet {
  id: string;
  text: string;
  likeCount: number;
  retweetCount: number;
  replyCount: number;
  quoteCount: number;
  viewCount: number;
  bookmarkCount: number;
}

REST API vs MCP Field Naming

REST examples show the default v1 response contract unless they explicitly send xquik-api-contract: 2026-04-29. The MCP server’s xquik.request() tool sends that normalized contract automatically in v2.5.4. MCP results use snake_case, date-time fields as Unix seconds, structured errors, has_more, and next_cursor. Pass next_cursor as cursor on most X data pages, as after for draws, extractions, events, and radar, or as afterCursor for drafts. A default createdAt field becomes created.

Type reference

Account

Returned by GET /api/v1/account. The creditInfo field is omitted when no credit balance record exists yet. creditInfo.balance shows the current credit count available for metered API calls.

API Keys

Two shapes exist: ApiKeyCreated is returned only from POST /api/v1/api-keys and includes the fullKey field. This is the only time the full key is exposed. ApiKey is returned by GET /api/v1/api-keys and shows only the prefix (first 8 characters) for identification.

Monitors

Account monitor endpoints return Monitor. The xUserId is the X (Twitter) user ID resolved from the username at creation time. Keyword monitor endpoints return KeywordMonitor with the normalized X search query. Both monitor types include eventTypes, isActive, createdAt, and nextBillingAt for active monitor billing.

Events

Event represents a single tracked action from an account or keyword monitor. monitorType is account or keyword; monitorId points to the source monitor. Account events include username; keyword events include query and keywordMonitorId. The data field contains tweet event data with id, text, author, isRetweet, isReply, isQuote, and createdAt. Replies include inReplyToId, quotes include a nested quoted_tweet object. Retweets are identified by isRetweet: true. See the TweetEventData interface in the Shared types tab for the full shape. EventList wraps paginated responses. Use nextCursor with the after query parameter to fetch subsequent pages.

Webhooks

Similar to API keys, webhooks have two shapes. WebhookCreated includes the secret field used for HMAC signature verification. Webhook (from list) never exposes the secret. If you lose the secret, delete and recreate the webhook.

Deliveries

Each Delivery represents one attempt to send an event to a webhook endpoint. Status progresses from pending to delivered (success) or through failed to exhausted (all retries failed). lastStatusCode and lastError help diagnose delivery failures.

Webhook payload

The WebhookPayload type describes the JSON body your endpoint receives on each delivery. Normal monitor events include schemaVersion, deliveryId, streamEventId, occurredAt, eventType, and data. Account monitor events include username; keyword monitor events include query. Verify authenticity with the X-Xquik-Signature header and your webhook secret. See Webhook Verification for implementation details.

webhook.test payloads include timestamp and omit monitor-only fields because they are not tied to a stored event. In normal event payloads, timestamp is omitted.

Draws

Draw is the full draw object returned by GET /api/v1/draws/{id} with tweet metadata and engagement counts. DrawListItem is the compact shape returned in list responses. DrawWinner contains the position, username, tweet ID, and backup flag for each winner. Filter fields on CreateDrawRequest control which entries qualify for the draw.

Extractions

ExtractionJob represents a completed or failed extraction job. The target fields (targetTweetId, targetUsername, etc.) vary by toolType. ExtractionResult contains the core user and tweet data returned by the API. Results are paginated in the get endpoint with up to 1,000 results per page. Exports (CSV, XLSX, Markdown) include additional enrichment columns not present in the API response. See Export Extraction for the full column list. ExtractionEstimate previews the cost before running a job.

X API

Direct X data lookup types. Tweet and TweetAuthor are returned by the tweet lookup endpoint. TweetSearchResult is returned in search results with an inline author object. UserProfile contains the full user profile. FollowerCheck returns the bidirectional follow relationship between two users. Both Tweet and TweetSearchResult include an optional media array of TweetMediaItem objects, present only when the tweet has attached media. Media types are photo, video, or animated_gif.

Trends

Trend represents a single trending topic on X. The description, rank, and query fields are omitted when unavailable. TrendList wraps the GET /api/v1/trends response. total is the number of trends returned, woeid is the region ID.

Radar

RadarItem represents a single trending topic or news item from Xquik’s own infrastructure. The source field identifies the Radar stream, and the metadata object contains stream-specific fields such as author, category, language, score, volume, views, or community signals when available. RadarList wraps paginated responses from GET /api/v1/radar. Use nextCursor with the after query parameter to fetch subsequent pages.

Styles

StyleProfile is returned by the analyze style (POST /api/v1/styles) and get style (GET /api/v1/styles/{id}) endpoints. It includes the cached tweets array with text, media, and timestamps. StyleListItem is the compact shape returned by GET /api/v1/styles (no tweets). StyleComparison wraps two full profiles for side-by-side comparison. PerformanceAnalysis adds engagement metrics (likes, retweets, replies, quotes, views, bookmarks) to each cached tweet. isOwnAccount is true when the analyzed username matches the authenticated user’s linked X identity.

Drafts

Draft represents a saved tweet draft. List, create, and get responses include id, text, createdAt, and updatedAt. Optional topic and goal fields are omitted (not null) when not set. DraftList wraps paginated responses. Use nextCursor with the afterCursor query parameter to fetch subsequent pages. Maximum 50 drafts per page.

X Accounts

XAccount represents a linked X account. displayName is the user’s display name on X. isActive indicates whether the account is currently connected and usable for API operations.

Compose

ComposeRequest drives the 3-step tweet composition flow: compose returns algorithm rules, follow-up questions, and an intentUrl built from the topic; refine returns composition guidance and example patterns; score evaluates a draft’s quality. styleUsername accepts a cached style username for voice matching. Compose responses can include savedStyles, styleTweets, or styleNote depending on the cached style state.

X Write

XWriteResponse is returned by write operations (post, retweet, like, reply). success indicates whether the operation completed. The optional data field contains platform-specific response data when available.

Support tickets

SupportTicket is the compact shape returned in list responses. SupportTicketDetail includes the full messages array. Each SupportMessage has a sender field indicating whether the message is from the user or support team. Status progresses from open through in_progress to resolved or closed.

Request bodies

All request body types use optional fields for update operations (PATCH) and required fields for creation (POST). The API validates request bodies and returns 400 invalid_input for missing or malformed fields.

Getting Started

SDKs

Guides

Webhooks

MCP Server

Agent Plugins

Framework Guides

OAuth

MPP

Resources

Type definitions

Usage

REST API vs MCP Field Naming

Type reference

Account

API Keys

Monitors

Events

Webhooks

Deliveries

Webhook payload

Draws

Extractions

X API

Trends

Radar

Styles

Drafts

X Accounts

Compose

X Write

Support tickets

Request bodies

​Usage

​REST API vs MCP Field Naming

​Type reference

​Account

​API Keys

​Monitors

​Events

​Webhooks

​Deliveries

​Webhook payload

​Draws

​Extractions

​X API

​Trends

​Radar

​Styles

​Drafts

​X Accounts

​Compose

​X Write

​Support tickets

​Request bodies

Usage

REST API vs MCP Field Naming

Type reference

Account

API Keys

Monitors

Events

Webhooks

Deliveries

Webhook payload

Draws

Extractions

X API

Trends

Radar

Styles

Drafts

X Accounts

Compose

X Write

Support tickets

Request bodies