Operations

Reminder: All queries on this page require the WORKSPACE-ID header. See Getting Started for setup.

Availability: This feature is not enabled by default. It requires a feature flag to be activated for your workspace. Contact your Customer Success Manager if you’d like access.

Operations allow you to trigger and track asynchronous background tasks via the API — starting with bulk engagement refresh. When you trigger a bulk operation, it runs in the background and you can poll its status using the operation query.

Refresh engagement data for multiple items

Use refetchEngagementBulk to queue a bulk engagement data refresh for a list of items. This is useful when you need up-to-date metrics (likes, views, EMV) for a specific set of items rather than waiting for Archive’s standard refresh schedule.

Credits: This mutation consumes credits — 3 credits per item refreshed. Credits are charged only for items accepted into the queue (skipped items are not charged).

Instagram Stories: Automatically excluded from bulk refresh — Stories are not supported.

Limit: Up to once per item per day.

mutation RefreshEngagement {
  refetchEngagementBulk(
    itemIds: [
      "a4b1c2d3-e5f6-7890-abcd-ef1234567890",
      "b5c2d3e4-f6a7-8901-bcde-fa2345678901"
    ]
  ) {
    operationId
    processedCount
    skippedItemIds
    userErrors { field message }
  }
}

Example response:

{
  "data": {
    "refetchEngagementBulk": {
      "operationId": "op-9182736-abc123",
      "processedCount": 2,
      "skippedItemIds": [],
      "userErrors": []
    }
  }
}

Response fields:

• operationId — ID of the background operation (use this to track progress). Returns null if no items were processable.
• processedCount — Number of items queued for refresh
• skippedItemIds — Items not queued because they’re already in an active refresh operation
• userErrors — Errors related to feature enablement or credit issues

Using with AI:

“Refresh the engagement data for these items: [item IDs]” “Queue an engagement refresh for all items in my ‘Q1 Campaign’ collection”

Refresh engagement data using URLs

The refetchEngagementBulk mutation requires item IDs — it does not accept URLs directly. However, you can combine it with itemIdsByUrl in two steps:

Step 1 — Translate URLs to item IDs:

query LookupUrls {
  itemIdsByUrl(urls: [
    "https://instagram.com/p/ABC123",
    "https://instagram.com/reel/DEF456"
  ]) {
    url
    status
    itemId
  }
}

Step 2 — Use the returned IDs to trigger the refresh:

mutation RefreshByUrl {
  refetchEngagementBulk(
    itemIds: [
      "item-id-from-step-1",
      "another-item-id"
    ]
  ) {
    operationId
    processedCount
    skippedItemIds
    userErrors { field message }
  }
}

Only items with status: FOUND in step 1 can be used. Items with NOT_FOUND or INVALID_URL won’t have a valid item ID.

Using with AI:

“Refresh the engagement data for these URLs: [paste URLs]”

Claude will run both steps automatically — translating URLs to IDs and then triggering the refresh.

Track operation status

After triggering a bulk refresh, use the operationId to track its progress:

query GetOperation {
  operation(id: "op-9182736-abc123") {
    id
    operationType
    status
    total
    processed
    createdAt
    completedAt
    succeededItemIds
    failedItemIds
    pendingItemIds
  }
}

Example response:

{
  "data": {
    "operation": {
      "id": "op-9182736-abc123",
      "operationType": "refetch_engagement",
      "status": "PROCESSING",
      "total": 2,
      "processed": 1,
      "createdAt": "2026-04-24T13:00:00Z",
      "completedAt": null,
      "succeededItemIds": ["a4b1c2d3-e5f6-7890-abcd-ef1234567890"],
      "failedItemIds": [],
      "pendingItemIds": ["b5c2d3e4-f6a7-8901-bcde-fa2345678901"]
    }
  }
}

Status values:

Using with AI:

“Check the status of operation op-9182736-abc123” “Is my bulk refresh done yet?”

List all operations

query ListOperations {
  operations(first: 20) {
    nodes {
      id
      operationType
      status
      total
      createdAt
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}

Example response:

{
  "data": {
    "operations": {
      "totalCount": 5,
      "nodes": [
        {
          "id": "op-9182736-abc123",
          "operationType": "refetch_engagement",
          "status": "COMPLETED",
          "total": 50,
          "createdAt": "2026-04-24T13:00:00Z"
        }
      ]
    }
  }
}

Using with AI:

“List all my recent operations” “Show me all completed refresh operations”