curl --request POST \
  --url https://api.paywithlocus.com/api/credits/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "goal": "Find 10 Series A hardware companies based in Los Angeles, California. Verify their funding, identify the founders and their verified work emails, and return a CSV."
}
'

{
  "object": "task",
  "version": "locus.task.v1",
  "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "queued",
  "terminal": true,
  "cost": {
    "unit": "credits",
    "max_credits": "<string>",
    "charged_credits": "<string>",
    "reserved_credits": "<string>",
    "accounting_state": "in_progress",
    "tool_credits": "<string>",
    "model_credits": "<string>",
    "paid_calls": 123
  },
  "stop_reason": "completed",
  "goal": "<string>",
  "question": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "deadline_at": "2023-11-07T05:31:56Z",
  "progress": {
    "phase": "<string>",
    "turns": 123,
    "paid_calls": 123,
    "last_event": {
      "type": "<string>",
      "at": "2023-11-07T05:31:56Z"
    }
  },
  "result": {
    "summary": "<string>",
    "executor_summary": "<string>",
    "data": {
      "columns": [
        "<string>"
      ],
      "rows": [
        {}
      ],
      "row_count": 123,
      "group_count": 123,
      "truncated": true
    },
    "answer": "<string>",
    "unverified_rows": [
      {
        "values": {},
        "reasons": [
          "<string>"
        ]
      }
    ]
  },
  "artifacts": [
    {
      "artifact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "results.csv",
      "kind": "result",
      "media_type": "<string>",
      "sha256": "<string>",
      "expires_at": "2023-11-07T05:31:56Z",
      "download_url": "<string>",
      "link_expires_at": "2023-11-07T05:31:56Z",
      "size_bytes": 123
    }
  ],
  "requirements": [
    {
      "id": "<string>",
      "text": "<string>",
      "status": "met",
      "mandatory": true,
      "detail": "<string>"
    }
  ],
  "assumptions": [
    "<string>"
  ],
  "limitations": [
    "<string>"
  ],
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "continuation": {
    "action": "wait",
    "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "hint": "<string>"
  }
}

{
  "object": "task",
  "version": "locus.task.v1",
  "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "queued",
  "terminal": true,
  "cost": {
    "unit": "credits",
    "max_credits": "<string>",
    "charged_credits": "<string>",
    "reserved_credits": "<string>",
    "accounting_state": "in_progress",
    "tool_credits": "<string>",
    "model_credits": "<string>",
    "paid_calls": 123
  },
  "stop_reason": "completed",
  "goal": "<string>",
  "question": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "deadline_at": "2023-11-07T05:31:56Z",
  "progress": {
    "phase": "<string>",
    "turns": 123,
    "paid_calls": 123,
    "last_event": {
      "type": "<string>",
      "at": "2023-11-07T05:31:56Z"
    }
  },
  "result": {
    "summary": "<string>",
    "executor_summary": "<string>",
    "data": {
      "columns": [
        "<string>"
      ],
      "rows": [
        {}
      ],
      "row_count": 123,
      "group_count": 123,
      "truncated": true
    },
    "answer": "<string>",
    "unverified_rows": [
      {
        "values": {},
        "reasons": [
          "<string>"
        ]
      }
    ]
  },
  "artifacts": [
    {
      "artifact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "results.csv",
      "kind": "result",
      "media_type": "<string>",
      "sha256": "<string>",
      "expires_at": "2023-11-07T05:31:56Z",
      "download_url": "<string>",
      "link_expires_at": "2023-11-07T05:31:56Z",
      "size_bytes": 123
    }
  ],
  "requirements": [
    {
      "id": "<string>",
      "text": "<string>",
      "status": "met",
      "mandatory": true,
      "detail": "<string>"
    }
  ],
  "assumptions": [
    "<string>"
  ],
  "limitations": [
    "<string>"
  ],
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "continuation": {
    "action": "wait",
    "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "hint": "<string>"
  }
}

{
  "success": false,
  "code": "TASK_REQUEST_INVALID",
  "message": "<string>"
}

{
  "success": false,
  "code": "TASK_REQUEST_INVALID",
  "message": "<string>"
}

{
  "success": false,
  "code": "TASK_REQUEST_INVALID",
  "message": "<string>"
}

{
  "success": false,
  "code": "TASK_REQUEST_INVALID",
  "message": "<string>"
}

{
  "success": false,
  "code": "TASK_REQUEST_INVALID",
  "message": "<string>"
}

Tasks

Run a task from a goal (submit, wait, cancel, respond, resume)

The single task interface. Without action, starts a task from a natural-language goal and waits up to wait_seconds for the result. With action wait/status/cancel/respond/resume it continues the same task; repeating wait or status never starts or charges anything. Locus discovers capabilities in the caller’s enabled catalog, calls them with the caller’s credits and spending controls, verifies values against stored provider responses, and computes the terminal state in code. It never sends messages, purchases, writes, or deletes on the caller’s behalf. Accepts secret keys and agent connections (MCP OAuth connections use the run_task MCP tool).

POST

credits

tasks

curl --request POST \
  --url https://api.paywithlocus.com/api/credits/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "goal": "Find 10 Series A hardware companies based in Los Angeles, California. Verify their funding, identify the founders and their verified work emails, and return a CSV."
}
'

{
  "object": "task",
  "version": "locus.task.v1",
  "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "queued",
  "terminal": true,
  "cost": {
    "unit": "credits",
    "max_credits": "<string>",
    "charged_credits": "<string>",
    "reserved_credits": "<string>",
    "accounting_state": "in_progress",
    "tool_credits": "<string>",
    "model_credits": "<string>",
    "paid_calls": 123
  },
  "stop_reason": "completed",
  "goal": "<string>",
  "question": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "deadline_at": "2023-11-07T05:31:56Z",
  "progress": {
    "phase": "<string>",
    "turns": 123,
    "paid_calls": 123,
    "last_event": {
      "type": "<string>",
      "at": "2023-11-07T05:31:56Z"
    }
  },
  "result": {
    "summary": "<string>",
    "executor_summary": "<string>",
    "data": {
      "columns": [
        "<string>"
      ],
      "rows": [
        {}
      ],
      "row_count": 123,
      "group_count": 123,
      "truncated": true
    },
    "answer": "<string>",
    "unverified_rows": [
      {
        "values": {},
        "reasons": [
          "<string>"
        ]
      }
    ]
  },
  "artifacts": [
    {
      "artifact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "results.csv",
      "kind": "result",
      "media_type": "<string>",
      "sha256": "<string>",
      "expires_at": "2023-11-07T05:31:56Z",
      "download_url": "<string>",
      "link_expires_at": "2023-11-07T05:31:56Z",
      "size_bytes": 123
    }
  ],
  "requirements": [
    {
      "id": "<string>",
      "text": "<string>",
      "status": "met",
      "mandatory": true,
      "detail": "<string>"
    }
  ],
  "assumptions": [
    "<string>"
  ],
  "limitations": [
    "<string>"
  ],
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "continuation": {
    "action": "wait",
    "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "hint": "<string>"
  }
}

{
  "object": "task",
  "version": "locus.task.v1",
  "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "queued",
  "terminal": true,
  "cost": {
    "unit": "credits",
    "max_credits": "<string>",
    "charged_credits": "<string>",
    "reserved_credits": "<string>",
    "accounting_state": "in_progress",
    "tool_credits": "<string>",
    "model_credits": "<string>",
    "paid_calls": 123
  },
  "stop_reason": "completed",
  "goal": "<string>",
  "question": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "deadline_at": "2023-11-07T05:31:56Z",
  "progress": {
    "phase": "<string>",
    "turns": 123,
    "paid_calls": 123,
    "last_event": {
      "type": "<string>",
      "at": "2023-11-07T05:31:56Z"
    }
  },
  "result": {
    "summary": "<string>",
    "executor_summary": "<string>",
    "data": {
      "columns": [
        "<string>"
      ],
      "rows": [
        {}
      ],
      "row_count": 123,
      "group_count": 123,
      "truncated": true
    },
    "answer": "<string>",
    "unverified_rows": [
      {
        "values": {},
        "reasons": [
          "<string>"
        ]
      }
    ]
  },
  "artifacts": [
    {
      "artifact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "results.csv",
      "kind": "result",
      "media_type": "<string>",
      "sha256": "<string>",
      "expires_at": "2023-11-07T05:31:56Z",
      "download_url": "<string>",
      "link_expires_at": "2023-11-07T05:31:56Z",
      "size_bytes": 123
    }
  ],
  "requirements": [
    {
      "id": "<string>",
      "text": "<string>",
      "status": "met",
      "mandatory": true,
      "detail": "<string>"
    }
  ],
  "assumptions": [
    "<string>"
  ],
  "limitations": [
    "<string>"
  ],
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "continuation": {
    "action": "wait",
    "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "hint": "<string>"
  }
}

{
  "success": false,
  "code": "TASK_REQUEST_INVALID",
  "message": "<string>"
}

{
  "success": false,
  "code": "TASK_REQUEST_INVALID",
  "message": "<string>"
}

{
  "success": false,
  "code": "TASK_REQUEST_INVALID",
  "message": "<string>"
}

{
  "success": false,
  "code": "TASK_REQUEST_INVALID",
  "message": "<string>"
}

{
  "success": false,
  "code": "TASK_REQUEST_INVALID",
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

Tenant secret key (lcr_…). Server-side only.

Headers

Idempotency-Key

string

Alternative to the body idempotency_key.

Maximum string length: 200

Body

application/json

goal

string

required

The outcome you want, in natural language.

Required string length: 1 - 8000

action

enum<string>

Optional; omitted means submit.

Available options:

submit

inputs

object

Optional caller data or references (for example urls, ids, rows). Treated as data, never as instructions. Max 256 KiB.

output

object

Show child attributes

max_credits

Credit ceiling for the whole task, including model reasoning and verification. In credits, not USD. Default 5 USD worth of credits, min 0.10 USD worth, max 200 USD worth; never above the account's own spending controls.

deadline_seconds

integer

Wall-clock limit for the task (default 900).

Required range: 180 <= x <= 3600

idempotency_key

string

Reuse to retry a submission safely; the same key with the same request returns the original task, with a different request it returns 409. The Idempotency-Key header is accepted too. Without a key every submission starts a new task, even with identical text.

Maximum string length: 200

wait_seconds

integer

Seconds to hold the request open for a result (default 45). The task keeps running after the response.

Required range: 0 <= x <= 50

Response

Terminal or needs_input envelope (or an idempotent replay of one).

object

enum<string>

required

Available options:

task

version

enum<string>

required

Available options:

locus.task.v1

task_id

string<uuid>

required

status

enum<string>

required

completed = every mandatory requirement met by checks; partial = useful verified subset; needs_input = answer question with action respond; unsupported = no enabled capability can do it; failed = nothing usable; canceled = caller canceled.

Available options:

queued,

running,

needs_input,

completed,

partial,

unsupported,

failed,

canceled

terminal

boolean

required

cost

object

required

Show child attributes

stop_reason

enum<string> | null

Available options:

completed,

count_shortfall,

requirements_unmet,

budget_exhausted,

insufficient_credits,

deadline,

canceled,

needs_input,

no_capability,

no_progress,

step_limit,

authorization_revoked,

execution_error,

null

goal

string

question

string

Present when status is needs_input.

created_at

string<date-time>

updated_at

string<date-time>

completed_at

string<date-time> | null

deadline_at

string<date-time>

progress

object

Show child attributes

result

object | null

Show child attributes

artifacts

object[]

Show child attributes

requirements

object[]

Show child attributes

assumptions

string[]

limitations

string[]

error

object

Present when the run recorded an execution error.

Show child attributes

continuation

object | null

Show child attributes

Overview

Endpoints

Run a task from a goal (submit, wait, cancel, respond, resume)

Authorizations

Headers

Body

Response