Run a matrix

curl --request POST \
  --url https://api.vaquill.ai/workspace/v1/matters/{matterId}/matrices/{matrixId}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "force": false
}'

import requests

url = "https://api.vaquill.ai/workspace/v1/matters/{matterId}/matrices/{matrixId}/runs"

payload = { "force": False }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({force: false})
};

fetch('https://api.vaquill.ai/workspace/v1/matters/{matterId}/matrices/{matrixId}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vaquill.ai/workspace/v1/matters/{matterId}/matrices/{matrixId}/runs"

	payload := strings.NewReader("{\n  \"force\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "op_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "type": "matrix.run",
  "status": "succeeded",
  "createdAt": "2026-08-19T14:32:10Z",
  "completedAt": "2026-08-19T14:32:10Z",
  "matterId": "mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "resource": {
    "kind": "matrix",
    "id": "mtx_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
    "url": "https://storage.vaquill.ai/exports/msa-acme-v3-redline.docx?signature=..."
  },
  "progress": {
    "done": 24,
    "total": 128,
    "unit": "cells"
  },
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "type": "<string>"
    }
  ],
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

Run a matrix

Extract every unanswered cell. 202 with an operation to poll.

An answer a person wrote, approved or rejected is left alone and is not charged for; force re-runs it and overwrites it. A run whose every eligible cell was stopped by a cancel is refused rather than accepted, because the extractor skips a cancelled cell and the run would otherwise do nothing while reporting success.

413 when the run is over the single-run cell ceiling, 429 when too many runs are already in flight, 503 when the guard deciding that cannot be reached. None of the three writes anything, so a refused run is free.

The 429 counts runs per PERSON rather than per organization, and the person is the human who provisioned this installation, so the three slots are shared with that person’s own matrix runs in the web app. An integration can be refused with no API run outstanding at all.

POST

matters

{matterId}

matrices

{matrixId}

runs

Run a matrix

curl --request POST \
  --url https://api.vaquill.ai/workspace/v1/matters/{matterId}/matrices/{matrixId}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "force": false
}'

import requests

url = "https://api.vaquill.ai/workspace/v1/matters/{matterId}/matrices/{matrixId}/runs"

payload = { "force": False }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({force: false})
};

fetch('https://api.vaquill.ai/workspace/v1/matters/{matterId}/matrices/{matrixId}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vaquill.ai/workspace/v1/matters/{matterId}/matrices/{matrixId}/runs"

	payload := strings.NewReader("{\n  \"force\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "op_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "type": "matrix.run",
  "status": "succeeded",
  "createdAt": "2026-08-19T14:32:10Z",
  "completedAt": "2026-08-19T14:32:10Z",
  "matterId": "mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "resource": {
    "kind": "matrix",
    "id": "mtx_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
    "url": "https://storage.vaquill.ai/exports/msa-acme-v3-redline.docx?signature=..."
  },
  "progress": {
    "done": 24,
    "total": 128,
    "unit": "cells"
  },
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "type": "<string>"
    }
  ],
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

{
  "type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential carries matters:read. This operation needs matters:write.",
  "instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
  "requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}

Authorizations

Authorization

string

header

required

Workspace credential issued from the automation console at /automation. Send it as Authorization: Bearer vq_ws_.... This is NOT a Data API key: a vq_key_ credential is refused here and names the other product in the error.

Headers

Idempotency-Key

string | null

A unique value of your choosing, so a retried launch returns the FIRST operation instead of starting a second billable job. Reusing one with a different body is refused. Retrying with the same key and the same body is free and is the intended way to recover from a timeout.

Path Parameters

matterId

string

required

mat_ identifier of the matter to work inside. Everything in this API hangs off a matter, and the matter in the path is what the authorization boundary is checked against. Take it from GET /v1/matters.

matrixId

string

required

mtx_ identifier of the matrix. Take it from the matter's matrix list.

Body

application/json

Start extraction.

An empty body runs every cell that has not answered yet. force re-runs cells that already have an answer, which is the only way to pick up an edited question, and is charged like any other run.

Cell, row and column subsetting is not published. The internal request accepts all three; each is a list of ids a customer would have to have read from a cells page first, and none of them changes what a customer can achieve, only how narrowly. The explicit cell_ids path is also the one that bypasses the terminal-status filter below, which is why schedule_run re-applies that filter by hand for it: publishing the subset would put the one path that can clobber a reviewed answer into the public contract.

force

boolean

default:false

False (the default) runs only cells that have not answered yet: never-run cells, failed cells, and cells that ran and found nothing. Answers you or a reviewer wrote, approved or rejected are left alone and are not charged for. True re-runs EVERY cell including those, OVERWRITING any answer a human wrote, approved or rejected, and charges for all of them. It is the only way to pick up an edited question.

Example:

false

Response

Successful Response

One long-running operation, whatever kind of work it is.

Readable for OPERATION_RETENTION_DAYS after creation, per AIP-151.

string

required

Public identifier, op_ followed by 32 hex characters. Poll GET /v1/operations/{operationId} with it.

Example:

"op_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"

type

string

required

What kind of work this is, for example matrix.run or draft.generate.

Example:

"matrix.run"

status

enum<string>

required

One of five values: queued, running, succeeded, failed, cancelled. There is no sixth and there are no synonyms. Stop polling once it is succeeded, failed or cancelled.

Available options:

queued,

running,

succeeded,

failed,

cancelled

Example:

"succeeded"

createdAt

string<date-time>

required

When the operation was accepted (RFC 3339).

Example:

"2026-08-19T14:32:10Z"

completedAt

string<date-time> | null

When the operation reached a terminal status (RFC 3339). Present if and only if the status is terminal.

Example:

"2026-08-19T14:32:10Z"

matterId

string | null

mat_ identifier of the matter this work belongs to, when it belongs to one.

Example:

"mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"

resource

OperationResource · object | null

What the operation produced. Absent until the underlying job row exists, which an idempotent replay can briefly observe, so treat absence as 'not yet' rather than 'never'.

Show child attributes

error

OperationError · object | null

Why the work failed. Present only when status is failed. Partial success is succeeded with progress.done < progress.total, never an error.

Show child attributes

progress

OperationProgress · object | null

How far along the work is, when the underlying job reports it. Absent does not mean no progress.

Show child attributes

requestId

string | null

The X-Request-ID of the request that created this operation. Quote it in a support ticket.

Example:

"req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"

Last modified on August 23, 2026

Chronology

Research

Clients

Comparisons

Compliance

Documents

Drafting

Facts

Folders

Matrices

Matter summary

Matters

NDA triage

Operations

Playbooks

Reviews

Uploads

Workflows

Run a matrix

Authorizations

Headers

Path Parameters

Body

Response