API Evangelist conversational phrasing for Parallel Tasks API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Parallel Tasks API
  version: 1.0.0
extends: openapi/parallel-tasks-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 12
- target: $.paths['/v1/tasks/groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a task group to batch runs
      effect: write
      questions:
      - How do I group many task runs together so I can track them as one batch?
      - Can I attach my own metadata to a task group when I create it?
      instructions:
      - text: Create a new task group.
      - text: Create a task group tagged with metadata {metadata}.
        slots:
          metadata: requestBody.metadata
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/tasks/groups/{taskgroup_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get aggregated status of a task group
      effect: read
      questions:
      - How many runs in my task group have finished versus are still running?
      - Can I see the overall progress of a batch of task runs at a glance?
      instructions:
      - text: Show the aggregated status of task group {taskgroup_id}.
        slots:
          taskgroup_id: path.taskgroup_id
      - text: Summarize progress across all runs in task group {taskgroup_id}.
        slots:
          taskgroup_id: path.taskgroup_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/tasks/groups/{taskgroup_id}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream status events for a task group
      effect: read
      questions:
      - Can I get live notifications as runs in a task group complete?
      - How long does a task group event stream stay open?
      instructions:
      - text: Stream status updates and run completions for task group {taskgroup_id}.
        slots:
          taskgroup_id: path.taskgroup_id
      - text: Resume task group {taskgroup_id} events after event {last_event_id}.
        slots:
          taskgroup_id: path.taskgroup_id
          last_event_id: query.last_event_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/tasks/groups/{taskgroup_id}/runs'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch the runs in a task group
      effect: read
      questions:
      - How do I get every run in a task group along with its inputs and outputs?
      - Can I fetch only the task group runs with a particular status?
      - Is the stream of task group runs resumable if it gets interrupted?
      instructions:
      - text: Fetch all runs in task group {taskgroup_id} with their outputs.
        slots:
          taskgroup_id: path.taskgroup_id
      - text: List the {status} runs in task group {taskgroup_id}.
        slots:
          status: query.status
          taskgroup_id: path.taskgroup_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/tasks/groups/{taskgroup_id}/runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a batch of task runs to a group
      effect: write
      questions:
      - How many task runs can I add to a task group in a single request?
      - Can I set a default task spec for all the runs I add to a group?
      instructions:
      - text: 'Add these runs to task group {taskgroup_id}: {inputs}.'
        slots:
          taskgroup_id: path.taskgroup_id
          inputs: requestBody.inputs
      - text: Queue {inputs} in task group {taskgroup_id} using default spec {default_task_spec}.
        slots:
          inputs: requestBody.inputs
          taskgroup_id: path.taskgroup_id
          default_task_spec: requestBody.default_task_spec
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/tasks/groups/{taskgroup_id}/runs/{run_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check one run inside a task group
      effect: read
      questions:
      - Can I look up the status of a single run within a specific task group?
      - Where do I check one run's status when I only know its group and run IDs?
      instructions:
      - text: Check the status of run {run_id} in task group {taskgroup_id}.
        slots:
          run_id: path.run_id
          taskgroup_id: path.taskgroup_id
      - text: Look up group {taskgroup_id} member run {run_id}.
        slots:
          taskgroup_id: path.taskgroup_id
          run_id: path.run_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/tasks/runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a web research task run
      effect: write
      questions:
      - How do I start a single research task with Parallel and get structured output?
      - Which processor should a task run use, and can I restrict which domains it searches?
      - Can a task run call my own MCP servers or notify a webhook when it's done?
      instructions:
      - text: Start a task run on the {processor} processor with input {input}.
        slots:
          processor: requestBody.processor
          input: requestBody.input
      - text: Run {input} with processor {processor} using task spec {task_spec}.
        slots:
          input: requestBody.input
          processor: requestBody.processor
          task_spec: requestBody.task_spec
      - text: Launch a {processor} task for {input} and call {webhook} when it completes.
        slots:
          processor: requestBody.processor
          input: requestBody.input
          webhook: requestBody.webhook
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/tasks/runs/{run_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a task run's status
      effect: read
      questions:
      - Is my task run still queued or has it finished?
      - How can I poll a task run's status without waiting for the result?
      instructions:
      - text: Check the status of task run {run_id}.
        slots:
          run_id: path.run_id
      - text: Tell me if task run {run_id} is done yet.
        slots:
          run_id: path.run_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/tasks/runs/{run_id}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream progress events for a task run
      effect: read
      questions:
      - Can I watch a task run's progress updates as they happen on the current v1 endpoint?
      - Will I get fewer progress events if I didn't enable events when creating the run?
      instructions:
      - text: Stream progress events for task run {run_id} using the v1 endpoint.
        slots:
          run_id: path.run_id
      - text: Follow task run {run_id} state changes live via v1.
        slots:
          run_id: path.run_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/tasks/runs/{run_id}/input'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the input a task run was given
      effect: read
      questions:
      - What input did I submit for a particular task run?
      - Can I retrieve the original prompt or JSON a task run started with?
      instructions:
      - text: Show the input of task run {run_id}.
        slots:
          run_id: path.run_id
      - text: Get what task run {run_id} was asked to research.
        slots:
          run_id: path.run_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/tasks/runs/{run_id}/result'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the output of a completed task run
      effect: read
      questions:
      - How do I get the final output of a task run once it completes?
      - Does fetching a task run's result block until it's finished, and can I set a timeout?
      instructions:
      - text: Get the result of task run {run_id}.
        slots:
          run_id: path.run_id
      - text: Wait up to {timeout} seconds for task run {run_id} output.
        slots:
          timeout: query.timeout
          run_id: path.run_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1beta/tasks/runs/{run_id}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream task run events (legacy v1beta)
      effect: read
      questions:
      - Is there still a v1beta endpoint for streaming task run events?
      - Can older beta integrations keep streaming task run progress from the beta path?
      instructions:
      - text: Stream events for task run {run_id} from the v1beta endpoint.
        slots:
          run_id: path.run_id
      - text: Use the legacy beta stream to follow task run {run_id}.
        slots:
          run_id: path.run_id
      method: generated
      generated: '2026-10-01'