# List task examples

> A task's examples in their shown order: the request that was sent and the files it sent and delivered.

`GET https://api.refabric.com/v1/tasks/{name}/examples`

**Authentication.** No key: a task's examples are the same for every reader.

**Common use cases**

- Copy an example's `request` and send it as it is to see the task run.
- Show what a task makes before anyone runs it.

**Conflicts.** A task that was removed answers `410 task_removed`; an unknown name `404`.

**See also**

- `GET /v1/tasks/{name}`
- `POST /v1/tasks/{name}`

Authentication: none — this operation needs no key.

## Path parameters

- `name` (string, _required_)

## Header parameters

- `Refabric-Version` (string, _optional_, format: date) — The contract version you wrote against (a date). Absent: the current version.
- `X-Request-ID` (string, _optional_, max length 128) — Your own id for this request; we answer it back under X-Client-Request-ID.

## Response 200

Done: the answer is in the body.

- `items` (array<object>, _required_) — Every example shown for the task, by position. Empty when it has none.
  - `id` (string, _required_) — The example's id, stable while it is shown.
    Example: `dex_4f1c`
  - `task` (string, _required_) — The task the request runs.
    Example: `image.generate`
  - `position` (integer, _required_) — Its place among the task's examples, first is 0.
    Example: `0`
  - `request` (object, _required_) — The request body exactly as it was sent to run the task, with each file it sent replaced by its copy in inputs. Send it as it is and the task runs again.
    Example: `{"prompt":"A linen summer dress on a beach at golden hour"}`
  - `inputs` (array<object>, _required_) — The files the request sent, in the order they appear in it.
    - `url` (string, _required_) — Where the file is. A public, permanent address you can open or download.
      Example: `https://files.refabric.com/art/3f2a.png`
    - `media_type` (string, _required_) — The file's standard media type.
      Example: `image/png`
    - `field` (string, _required_) — The request field the file was sent in, as a path into the request.
      Example: `image`
  - `outputs` (array<object>, _required_) — The files the job delivered.
    Example: `[{"media_type":"image/png","url":"https://example.com/docs/examples/image.generate/dex_4f1c-out-0.png"}]`
    - `url` (string, _required_) — Where the file is. A public, permanent address you can open or download.
      Example: `https://files.refabric.com/art/3f2a.png`
    - `media_type` (string, _required_) — The file's standard media type.
      Example: `image/png`
    - `poster_url` (string | null, _required_) — For a video, a still frame to show before it plays; null otherwise.
  - `caption` (string, _required_) — A short note on what the example shows; may be empty.
    Example: `Golden-hour light on linen.`

```json
{
  "items": []
}
```

## Response 401

No valid API key was sent.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 403

Your key or your plan does not allow this.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 404

Nothing has this address.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 410

This was removed.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 429

Too many requests: wait for the number of seconds in the Retry-After header.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 500

Something went wrong on our side; retry, and quote the request id if it keeps happening.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Request

```python
import requests

url = "https://api.refabric.com/v1/tasks/{name}/examples"

response = requests.get(url)

print(response.json())
```

```javascript
const url = 'https://api.refabric.com/v1/tasks/{name}/examples';
const options = {method: 'GET'};

try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
} catch (error) {
    console.error(error);
}
```

```bash
curl --request GET \
    --url https://api.refabric.com/v1/tasks/{name}/examples
```