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

# Run 조회

> Run 목록과 이벤트 타임라인을 커서 방식으로 조회합니다.

Run 조회 API는 별도 운영 화면, 데이터 내보내기, 연동 테스트에 사용할 수 있습니다. `usage:read` 권한이 필요합니다.

## Run 목록

```http theme={null}
GET /openapi/v1/runs?limit=25&status=FAILED
X-API-Key: YOUR_WORKSPACE_API_KEY
```

쿼리 파라미터:

| 파라미터      | 설명                                                     |
| --------- | ------------------------------------------------------ |
| `limit`   | 1부터 100까지 지정합니다. 기본값은 25입니다.                           |
| `cursor`  | 이전 응답의 `nextCursor`를 그대로 전달합니다.                        |
| `agentId` | Lynx 내부 Agent UUID로 필터링합니다.                            |
| `status`  | `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED` 중 하나입니다. |

```json theme={null}
{
  "items": [
    {
      "id": "ebd7c740-e284-4db1-86c0-6c1a78eb30f8",
      "runId": "run_01JZQ3VY4K",
      "status": "FAILED",
      "startedAt": "2026-07-23T08:00:00.000Z",
      "endedAt": "2026-07-23T08:00:02.120Z",
      "agent": {
        "id": "aa971534-cce6-4ca8-a950-99f8e779ae0a",
        "name": "support-agent"
      },
      "usage": {
        "promptTokens": 240,
        "completionTokens": 32,
        "totalTokens": 272,
        "cost": 0.0021
      }
    }
  ],
  "nextCursor": null
}
```

커서는 내부 형식에 의존하지 말고 불투명한 문자열로 다루세요. 직접 만들거나 해석하지 않는 것이 좋습니다.

## Run 하나 조회

```http theme={null}
GET /openapi/v1/runs/run_01JZQ3VY4K
```

경로에는 Lynx 내부 Run UUID나 클라이언트가 만든 `runId`를 사용할 수 있습니다. 응답에는 이벤트가 최대 100개까지 포함되며, 더 남아 있으면 `hasMoreEvents`가 `true`입니다.

## 이벤트 계속 조회

`hasMoreEvents`가 `true`이면 다음 경로를 호출합니다.

```http theme={null}
GET /openapi/v1/runs/run_01JZQ3VY4K/events?limit=100
```

응답의 `nextCursor`를 다음 요청에 그대로 전달합니다.

```json theme={null}
{
  "items": [
    {
      "id": "63782fe2-11ed-49a7-869e-4da55a445641",
      "eventId": "evt_llm_01",
      "eventType": "LLM_CALL",
      "label": "Choose payment action",
      "timestamp": "2026-07-23T08:00:01.000Z",
      "payload": {
        "model": "model-name"
      }
    }
  ],
  "nextCursor": null
}
```

이벤트는 페이지당 최대 200개이며 기본값은 100개입니다.

<Warning>
  Run payload에는 프롬프트, 도구 인자, 모델 응답이 들어갈 수 있습니다. 자체
  서비스에서 이 API를 노출할 때 별도 사용자 권한을 확인하고 원본 payload를
  애플리케이션 로그에 복사하지 마세요.
</Warning>