List runs

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

# List runs

> List run summaries for one test set.

Returns paginated run summaries for one test set, newest first.

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token containing your Fini workspace API key. Format: `Bearer fini_...` The key needs `read` scope.
</ParamField>

## Path parameters

<ParamField path="testSetId" type="string" required>
  Test set ID.
</ParamField>

## Query parameters

<ParamField query="limit" type="number" default="50">
  Number of runs to return. Minimum `1`, maximum `100`.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of runs to skip.
</ParamField>

## Response

Returns an array of [Run objects](/en/api-reference/test-sets#run-object).

<RequestExample>
  ~~~bash cURL theme={null}
  curl --request GET \
    --url 'https://api-prod.usefini.com/v2/test-sets/44c1f705-8e1a-4f61-8c4c-d519d37fb6b7/runs/public?limit=25&offset=0' \
    --header 'Authorization: Bearer fini_your_api_key'
  ~~~

  ~~~javascript Node.js theme={null}
  const testSetId = '44c1f705-8e1a-4f61-8c4c-d519d37fb6b7';
  const params = new URLSearchParams({ limit: '25', offset: '0' });

  const response = await fetch(`https://api-prod.usefini.com/v2/test-sets/${testSetId}/runs/public?${params}`, {
    method: 'GET',
    headers: {
      Authorization: 'Bearer fini_your_api_key'
    }
  });

  const runs = await response.json();
  ~~~

  ~~~python Python theme={null}
  import requests

  test_set_id = "44c1f705-8e1a-4f61-8c4c-d519d37fb6b7"

  response = requests.get(
      f"https://api-prod.usefini.com/v2/test-sets/{test_set_id}/runs/public",
      headers={"Authorization": "Bearer fini_your_api_key"},
      params={"limit": 25, "offset": 0},
  )

  runs = response.json()
  ~~~
</RequestExample>

<ResponseExample>
  ~~~json 200 OK theme={null}
  [
    {
      "id": "5afd818a-a5f9-4e1b-9619-3c7191c12d9a",
      "testSetId": "44c1f705-8e1a-4f61-8c4c-d519d37fb6b7",
      "status": "completed",
      "result": {
        "summary": {
          "testSetResult": "pass",
          "totalConversations": 2,
          "passedConversations": 2,
          "failedConversations": 0,
          "errorConversations": 0,
          "totalCriteria": 2,
          "passedCriteria": 4,
          "failedCriteria": 0
        },
        "conversations": [
          {
            "hcInteractionId": "a5221094-72d4-4b9c-8d30-2f785b108bd9",
            "result": "pass",
            "error": null,
            "criteriaResults": [
              {
                "criteriaId": "96eab02d-3bc3-4b90-ae5b-1a41a1444afa",
                "name": "Goal resolution",
                "type": "complex_judge",
                "blocking": true,
                "result": "pass",
                "reasoning": "The answer resolved the refund-policy question.",
                "evidence": ["The agent explained eligibility and next steps."]
              }
            ]
          }
        ]
      },
      "createdBy": null,
      "createdAt": "2026-07-28T09:01:14.000Z",
      "updatedAt": "2026-07-28T09:02:09.000Z"
    }
  ]
  ~~~
</ResponseExample>


## Related topics

- [Overview](/en/api-reference/test-sets.md)
- [API overview](/en/api-reference/overview.md)
- [List guardrail runs](/en/api-reference/list-guardrail-runs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.