> For the complete documentation index, see [llms.txt](https://everyday-digital.gitbook.io/falkor-dev-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://everyday-digital.gitbook.io/falkor-dev-docs/stories/logs/story-logs.md).

# Story Logs

## Parameters

All parameters are optional and if none are provided all stories, users and groups will be called.

<table><thead><tr><th width="158"></th><th></th></tr></thead><tbody><tr><td><strong>Key</strong></td><td><strong>Type</strong></td></tr><tr><td><strong>app</strong></td><td>String (ID or name of app)</td></tr><tr><td><strong>story</strong></td><td>String (ID or name of story)</td></tr><tr><td><strong>groups</strong></td><td>Array String (name of group)</td></tr><tr><td><strong>users</strong></td><td>Array String (name or email)</td></tr></tbody></table>

{% hint style="info" %}
**Story Limit**

This endpoint retrieves **only 1 story**. If you need to retrieve all story data use the  [`logs/user-story-logs`](/falkor-dev-docs/stories/logs/story-logs-alpha-release.md) endpoint instead.
{% endhint %}

## Examples

### Fetch logs for specific groups

The example below retrieves all users and stories for a given array of groups.

```
curl -X POST \
  v1/logs/story-logs \
  -H 'Authorization: Basic <Your Base64 Encoded Token>' \
  -d ' {
    "story" : "Story 1"
    "groups" : ["Group A","Group B",...etc]
  }'
```

### Fetch logs for a specific story

The example below retrieves all users for a given story.

```
curl -X POST \
  v1/logs/story-logs \
  -H 'Authorization: Basic <Your Base64 Encoded Token>' \
  -d ' {
    "story" : "Story 1"
  }'
```

### Fetch logs for specific users

The example below retrieves logs users for a given array of emails.

```
curl -X POST \
  logs/story-logs \
  -H 'Authorization: Basic <Your Base64 Encoded Token>' \
  -d ' {
    "story" : "Story 1"
    "users" : ["one@example.com","Joe Soap",...etc]
  }'
```

### Full Example

The example below retrieves logs for specific users & stories in certain groups.

```
curl -X POST \
  logs/story-logs \
  -H 'Authorization: Basic <Your Base64 Encoded Token>' \
  -d ' {
    "groups" : ["Group A"],
    "story"  : "Story 1",
    "emails" : ["one@example.com","two@example",...etc]
  }'
```

## Success Response

The response returns a list of `story` + `logs` items.

```
{
    "status": "success",
    "data": [
        {
            "story": {
                "ID": "EV72-RQZY-80AH",
                "name": "Story A",
                "type" : "assessment",
                "app": {
                    "ID": "io.falkor.demo",
                    "name": "Falkor",
                    "version": "2.5.0"
                }
            },
            "logs": [
                {
                    "firstname": "User",
                    "lastname": "One",
                    "email": "user.one@example.com",
                    "telephone": "",
                    "country": "United Kingdom",
                    "city": "London",
                    "groups": [
                        "Group A",
                        "Group B"
                    ],
                    "status": {
                        "complete": true,
                        "score": 100,
                        "passed": true,
                        "duration": 19,
                        "attempts": 1,
                        "started": "2022-02-24T14:56:32+02:00",
                        "updated": "2022-02-24T14:56:53+02:00"
                    }
                },
                ...etc
            ]
        },
        {
            "story": {
                "ID": "EV10-JOPK-88UH",
                "name": "Story B",
                "type": "scorm",
                "app": {
                    "ID": "io.falkor.acme",
                    "name": "Acme App",
                    "version": "2.9.0"
                }
            },
            "logs": [
                {
                    "firstname": "User",
                    "lastname": "Two",
                    "email": "user.two@example.com",
                    "telephone": "",
                    "country": "South Africa",
                    "city": "Cape Town",
                    "groups": [],
                    "status": {
                        "complete": true,
                        "duration": 19,
                        "attempts": 1,
                        "started": "2022-02-24T14:56:32+02:00",
                        "updated": "2022-02-24T14:56:53+02:00"
                    }
                },
                ...etc
            ]
        },
        ...etc
    ],
    "hash": "b00bb9cc0573f8b4e153a5cd4421dc67",
    "response_time": 0.3414289951324463
}
```

### Story + Logs Item

|                |                                            |
| -------------- | ------------------------------------------ |
| **Key**        | **Type**                                   |
| **story**      | Object                                     |
| **story.ID**   | String                                     |
| **story.name** | String                                     |
| **story.type** | Enum (assessment, story, survey, scorm)    |
| **story.app**  | Object (the app the story is published to) |
| **logs**       | Array of Log Items                         |

### Log Items

{% hint style="info" %}
**Please Note:** Only assessment or stories that have assessment activities will have a passed and score parameter. Non-scoring stories such as surveys will not have these parameters.
{% endhint %}

<table><thead><tr><th width="231.47823702859256"></th><th></th></tr></thead><tbody><tr><td><strong>Key</strong></td><td><strong>Type</strong></td></tr><tr><td><strong>firstname</strong></td><td>String</td></tr><tr><td><strong>lastname</strong></td><td>String</td></tr><tr><td><strong>email</strong></td><td>String</td></tr><tr><td><strong>telephone</strong></td><td>String</td></tr><tr><td><strong>country</strong></td><td>String</td></tr><tr><td><strong>city</strong></td><td>String</td></tr><tr><td><strong>groups</strong></td><td>Array String (Assigned groups)</td></tr><tr><td><strong>status</strong></td><td>Object</td></tr><tr><td><strong>status.complete</strong></td><td>Bool (If the story has been completed)</td></tr><tr><td><strong>status.duration</strong></td><td>Int (Total time spent in seconds)</td></tr><tr><td><strong>status.attempts</strong></td><td>Int (Total attempts)</td></tr><tr><td><strong>status.started</strong></td><td>String (Time when first attempt was started)</td></tr><tr><td><strong>status.updated</strong></td><td>String (Timestamp when the last attempt was updated.)</td></tr><tr><td>SCORING STORY ONLY</td><td></td></tr><tr><td><strong>status.score</strong></td><td>Float. Percentage scored</td></tr><tr><td><strong>status.passed</strong></td><td>Bool. If the pass mark was achieved.</td></tr></tbody></table>