Mutation

createDeepResearchReport

Start a Deep Research report in the current workspace; it spends credits.

MCP: createDeepResearchReport

Arguments

Object, input and enum types open in place — use + to reveal their fields. A type that is already open above the row stops at a ↻ circular marker, and anything nested past the depth limit links out to its own page instead.

input DeepResearchReportInput! required: Mutation input.
brandIds [ID!]: BRAND: competitor brand UUIDs (competitorBrands). How many brands a report takes is set per template, and a count outside its bounds is refused with the bounds in the message. A single-brand template takes exactly one brand: your own (the entry with isOwnBrand: true) or one competitor. A multi-brand template (e.g. Share of Voice) always includes your own brand, so pass competitors only, at least as many as the template asks for; your own brand is not one of them.
campaignId ID: CAMPAIGN: the campaign UUID (campaigns).
commentCount Int: Comments read per post when includeComments is true.
creatorId ID: CREATOR: the creator UUID (creators).
from DateWithZone: BRAND: first day of the window. Defaults to the first day of the previous month.
includeComments Boolean: Read the comments under each post, where the template allows (audienceComments).
includeReplies Boolean: Also read replies to those comments.
inputType DeepResearchInputType! required: What the report runs on. deepResearchTemplates lists which types each template accepts.
BRAND: Tracked competitor brands (brandIds), including your own brand, over a date window.
CAMPAIGN: A campaign (campaignId): the report reads the campaign's content.
CREATOR: A creator (creatorId, optionally narrowed to socialProfileIds).
VIEW: A saved content view (viewId): the report reads the posts the view matches.
name String: Report title. Defaults to one derived from the template and source.
poolSize Int: BRAND, pooled Share of Voice templates only: candidate posts ranked before the per-brand limit.
postLimitPerBrand Int: BRAND: posts read per brand. Defaults to the template's recommendation.
prompt String: Extra instructions for the analysis.
repliesPerParent Int: Replies read per comment when includeReplies is true.
replyParentLimit Int: Comments per post whose replies are read when includeReplies is true.
socialProfileIds [ID!]: CREATOR: narrow the report to these of the creator's social profile UUIDs.
templateSlug String! required: The template to run, as slug in deepResearchTemplates.
to DateWithZone: BRAND: last day of the window. Defaults to the last day of the previous month.
trackedCommentsOnly Boolean: Read only the comments this workspace tracks (Social Flirting workspaces).
viewId ID: VIEW: the content view UUID (contentViews).

Returns

deepResearchReport DeepResearchReport: The new report, still running. Null when the input was refused.
completedAt DateTimeWithZone: When it completed; null while running or after a failure.
createdAt DateTimeWithZone: When the report was created.
errorMessage String: Why a failed report failed.
id ID!: Report UUID. Pass it to deepResearchReport(id:) to poll it.
inputType DeepResearchInputType: The source kind it ran on; null when Deep Research did not say or the source is not one of the DeepResearchInputType kinds.
BRAND: Tracked competitor brands (brandIds), including your own brand, over a date window.
CAMPAIGN: A campaign (campaignId): the report reads the campaign's content.
CREATOR: A creator (creatorId, optionally narrowed to socialProfileIds).
VIEW: A saved content view (viewId): the report reads the posts the view matches.
markdown String: The finished report as Markdown. Returned by deepResearchReport(id:) only, once the report has completed; null in deepResearchReports and while it runs.
phase String: The step a running report is on.
postsAnalyzed Int: How many posts it read.
progressMessage String: Human-readable progress of a running report.
running Boolean!: Whether Deep Research still lists the report as in flight; poll until it is false. False for COMPLETED, FAILED and CANCELLED, and for a PROCESSING report an earlier version of Deep Research left paused. It follows the status Deep Research holds, not whether work is happening: a report that stalls in flight stays true until Deep Research fails or cancels it, so cap how long you poll, for example by giving up once createdAt is hours old.
shareUrl String: Public link to the finished report; null until it completes.
sourceId String: Id of the source it ran on.
sourceName String: Name of the source it ran on.
status DeepResearchReportStatus!: Lifecycle status: PENDING, FETCHING and PROCESSING are in flight; COMPLETED, FAILED and CANCELLED are final. A report can also read PROCESSING while it is in a step this list does not name separately. Use running, not the status, to decide whether to keep polling.
CANCELLED: Stopped before it finished; it will not complete.
COMPLETED: Finished: shareUrl is set, and deepResearchReport(id:) returns its markdown.
FAILED: Stopped by an error; errorMessage says why.
FETCHING: Reading the posts it will analyze.
PENDING: Created, not started yet.
PROCESSING: Analyzing them and writing the report. A report also reads PROCESSING when an earlier version of Deep Research left it paused between fetching and analysis, or when it is in a step this list does not name separately; check running, which is false for the paused case. The PROCESSING filter matches neither case.
templateSlug String: The template the report ran.
title String: The report title, as the Archive app shows it.
userErrors [UserError!]!: Why the report was not started: invalid input (pointing at the field) or not enough credits. Empty on success.
field [String!]: Path to the input field that caused the error.
message String!: The error message.

Open in explorer ↗

Values are sampled from a demo workspace — substitute your own token and workspace id.

Start a Share of Voice report on two tracked competitors. It spends the workspace's credits, so quote it first; poll `deepResearchReport(id:)` until `running` is false.

query.graphql

mutation CreateDeepResearchReportDefault($input: DeepResearchReportInput!) {
  createDeepResearchReport(input: $input) {
    deepResearchReport {
      id
      status
      running
    }
    userErrors {
      field
      message
    }
  }
}

variables.json

{
  "input": {
    "inputType": "BRAND",
    "templateSlug": "share-of-voice",
    "brandIds": [
      "28add94e-9994-54b2-9aaa-528e6606efe9",
      "97eb8f2a-7cf3-596f-b283-08dde96550e0"
    ]
  }
}

Headers

Authorization: Bearer docs_demo_token_0000000000000000000000
WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a

Request · cURL

curl https://app.archive.com/api/v2 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer docs_demo_token_0000000000000000000000' \
  -H 'WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a' \
  -d '{
  "query": "mutation CreateDeepResearchReportDefault($input: DeepResearchReportInput!) {\n  createDeepResearchReport(input: $input) {\n    deepResearchReport {\n      id\n      status\n      running\n    }\n    userErrors {\n      field\n      message\n    }\n  }\n}",
  "variables": {
    "input": {
      "inputType": "BRAND",
      "templateSlug": "share-of-voice",
      "brandIds": [
        "28add94e-9994-54b2-9aaa-528e6606efe9",
        "97eb8f2a-7cf3-596f-b283-08dde96550e0"
      ]
    }
  }
}'

Request · Node.js

const response = await fetch("https://app.archive.com/api/v2", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer docs_demo_token_0000000000000000000000",
    "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a"
  },
  body: JSON.stringify({
    query: `mutation CreateDeepResearchReportDefault($input: DeepResearchReportInput!) {
  createDeepResearchReport(input: $input) {
    deepResearchReport {
      id
      status
      running
    }
    userErrors {
      field
      message
    }
  }
}`,
    variables: {
      "input": {
        "inputType": "BRAND",
        "templateSlug": "share-of-voice",
        "brandIds": [
          "28add94e-9994-54b2-9aaa-528e6606efe9",
          "97eb8f2a-7cf3-596f-b283-08dde96550e0"
        ]
      }
    }
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

Request · Ruby

require "json"
require "net/http"

query = <<~'GRAPHQL'
  mutation CreateDeepResearchReportDefault($input: DeepResearchReportInput!) {
    createDeepResearchReport(input: $input) {
      deepResearchReport {
        id
        status
        running
      }
      userErrors {
        field
        message
      }
    }
  }
GRAPHQL

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query, variables: { "input" => { "inputType" => "BRAND", "templateSlug" => "share-of-voice", "brandIds" => ["28add94e-9994-54b2-9aaa-528e6606efe9", "97eb8f2a-7cf3-596f-b283-08dde96550e0"] } } }.to_json,
  "Content-Type" => "application/json",
  "Authorization" => "Bearer docs_demo_token_0000000000000000000000",
  "WORKSPACE-ID" => "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a"
)
puts response.body

Request · Python

import json
import requests

query = """
mutation CreateDeepResearchReportDefault($input: DeepResearchReportInput!) {
  createDeepResearchReport(input: $input) {
    deepResearchReport {
      id
      status
      running
    }
    userErrors {
      field
      message
    }
  }
}
"""

response = requests.post(
    "https://app.archive.com/api/v2",
    json={"query": query, "variables": {"input": {"inputType": "BRAND", "templateSlug": "share-of-voice", "brandIds": ["28add94e-9994-54b2-9aaa-528e6606efe9", "97eb8f2a-7cf3-596f-b283-08dde96550e0"]}}},
    headers={
        "Authorization": "Bearer docs_demo_token_0000000000000000000000",
        "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
    },
)
print(json.dumps(response.json(), indent=2))

200 OK 12 lines

{
  "data": {
    "createDeepResearchReport": {
      "deepResearchReport": {
        "id": "475b666e-f1a3-5019-a216-f599aed6cce0",
        "status": "PENDING",
        "running": true
      },
      "userErrors": []
    }
  }
}