Agent tasks

Agent tasks are the other direction of the approval inbox: instead of the agent asking a person, a person leaves the agent a job. The agent reads its queue, works on a task with the normal RankParse tools, then reports back with a short summary that the person sees in the app.

This page covers the three task routes and POST /v1/activity, which lets an agent write a note into the website's activity feed. All four cost 0 credits, use your X-API-Key, and share the 60 requests per minute limit.

Where tasks come from

• A person types a job into Give your agent a task on a website in the RankParse dashboard, or uses an Ask agent button. Tasks are stored for the agent to pick up only on accounts where agent proposals are available.
• When a person approves a rank-drop investigation that RankParse proposed, approving it creates a task asking the agent to find the cause and report back.

Every task has an origin (task_box, proposal, rankings_row or domain_view) so you can tell which.

List tasks

Only tasks that have not expired are returned, newest first, at most 50.

curl "https://api.rankparse.com/v1/agent-tasks?status=open" \
  -H "X-API-Key: rp_your_key"

import requests

res = requests.get(
    "https://api.rankparse.com/v1/agent-tasks",
    headers={"X-API-Key": "rp_your_key"},
    params={"status": "open"},
)
for task in res.json()["tasks"]:
    print(task["id"], task["prompt"])

const res = await fetch("https://api.rankparse.com/v1/agent-tasks?status=open", {
  headers: { "X-API-Key": "rp_your_key" },
});
const { tasks } = await res.json();
for (const task of tasks) console.log(task.id, task.prompt);

{
  "tasks": [
    {
      "id": "tsk_K3mP9xQ2vLw8Rt5Yn1BzA",
      "site_id": "site_abc123",
      "site_host": "example.com",
      "prompt": "Find links my competitors have",
      "status": "open",
      "origin": "task_box",
      "created_at": 1790000000000,
      "expires_at": 1791209600000,
      "claimed_at": null,
      "completed_at": null,
      "result_summary": null
    }
  ]
}

Task fields

No workspace, user or credential identifiers are ever returned.

Claim a task

Claiming marks the task as yours so other agents on the same account leave it alone. It takes no body.

curl -X POST "https://api.rankparse.com/v1/agent-tasks/tsk_K3mP9xQ2vLw8Rt5Yn1BzA/claim" \
  -H "X-API-Key: rp_your_key"

Returns { "task": { ... } } with status: "claimed" and claimed_at set.

• Claiming again with the same key is a no-op that returns the task, so retrying after a network error is safe.
• A task that is done, expired, cancelled, or claimed by a different key returns 409 task_not_claimable.
• Claiming is optional. Completing an open task claims it implicitly.

Complete a task

curl -X POST "https://api.rankparse.com/v1/agent-tasks/tsk_K3mP9xQ2vLw8Rt5Yn1BzA/complete" \
  -H "X-API-Key: rp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"summary": "Found 12 domains linking to two competitors but not to you. Top three: alpha.com, beta.org, gamma.io."}'

import requests

res = requests.post(
    "https://api.rankparse.com/v1/agent-tasks/tsk_K3mP9xQ2vLw8Rt5Yn1BzA/complete",
    headers={"X-API-Key": "rp_your_key"},
    json={"summary": "Found 12 domains linking to two competitors but not to you."},
)
print(res.json()["task"]["status"])  # "done"

const res = await fetch(
  "https://api.rankparse.com/v1/agent-tasks/tsk_K3mP9xQ2vLw8Rt5Yn1BzA/complete",
  {
    method: "POST",
    headers: { "X-API-Key": "rp_your_key", "Content-Type": "application/json" },
    body: JSON.stringify({
      summary: "Found 12 domains linking to two competitors but not to you.",
    }),
  },
);
console.log((await res.json()).task.status); // "done"

Returns { "task": { ... } } with status: "done", completed_at and result_summary set. Completing a task that is still open claims it for your key in the same step. A task claimed by another key, or already done, expired or cancelled, returns 409 task_not_claimable.

Log activity

Writes a short note into the website's activity feed, so the team can see what the agent did even when nothing needed approval.

Unknown fields (for example a credits number) return 400 invalid_activity_input.

curl -X POST "https://api.rankparse.com/v1/activity" \
  -H "X-API-Key: rp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Researched 40 prospects and drafted 12 emails for review.",
    "site_id": "site_abc123",
    "kind_hint": "research",
    "client_request_id": "run-2026-10-11-a"
  }'

{
  "id": "act_Qm3N8vLp2Xw5Zt9RbYk1C",
  "credits": 6,
  "calls": 3,
  "duplicate": false
}

You never report your own credit use. RankParse attaches the unattributed calls your key made in the last 24 hours to the note automatically, so the activity feed shows what each piece of work actually cost. A repeat of the same client_request_id claims nothing again.

Limits: 200 notes per account per UTC day (429 activity_limit_reached). Notes are visible to the team, not to clients, unless a team member shares one.

Errors

See also Error codes.

Retention

Tasks, activity and terminal proposals are kept for 400 days. Agent notes attached to finished proposals are cleared after 90 days.

Related

MCP tools: get_agent_tasks, complete_agent_task and log_activity on the API-key MCP endpoint (there is no tool for claiming, because completing a task claims it). See MCP server.