> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Acquire Next Pending Job for Node Agent

> Node agents long-poll this endpoint to acquire the next pending training job assigned to them by the PIN control plane.

Node agents call this endpoint to acquire the next pending job. The controller long-polls: it returns immediately when a matching job is available, otherwise it returns `204 No Content` after a bounded wait so the agent can retry.

<Warning>
  This endpoint is called by node agents, not by end users. It requires the `X-Agent-Secret` header issued when the agent registers.
</Warning>

## Endpoint

```http theme={null}
POST /v1/agent/acquire
```

## Authentication

`X-Agent-Secret: <agent_secret>`.

## Request body

<ParamField body="agent_id" type="string" required>
  Stable agent identifier returned by [Register](/api-reference/pin/node-agent/register).
</ParamField>

<ParamField body="capabilities" type="object">
  Current capability snapshot, including free GPU indices and VRAM.
</ParamField>

## Response

Returns `204 No Content` when no job is available. On a match, returns the PIN envelope with the job payload.

<ResponseField name="code" type="integer">
  `0` on match.
</ResponseField>

<ResponseField name="data" type="object">
  Full job payload: `job_id`, `type`, `base_model`, `dataset_id`, `lora`, `hyperparams`, `assigned_gpu_index`.
</ResponseField>

## Example

```bash theme={null}
curl -X POST https://ariapin.example.com/v1/agent/acquire \
  -H "X-Agent-Secret: $AGENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "ag_01", "capabilities": {"free_gpus": [0, 1]}}'
```

```json theme={null}
{
  "code": 0,
  "data": {
    "job_id": "job_0198a...",
    "type": "sft",
    "base_model": "meta-llama/Llama-3-8B",
    "assigned_gpu_index": 0
  },
  "message": ""
}
```


## Related topics

- [Node Agent Control Channel and Interventions](/api-reference/pin/node-agent/control.md)
- [Node Agent Heartbeat](/api-reference/pin/node-agent/heartbeat.md)
- [Delete a GPU Node](/api-reference/pin/gpu-nodes/delete.md)
- [Report Training Metrics and Status - Node Agent](/api-reference/pin/node-agent/metrics.md)
- [Delete an Agent](/api-reference/pin/agents/delete.md)