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

# Api

<a id="literalai.api.__init__" />

<a id="literalai.api.__init__.LiteralAPI" />

## LiteralAPI

```python theme={null}
class LiteralAPI(BaseLiteralAPI)
```

```python theme={null}
from literalai import LiteralClient
# Initialize the client
literalai_client = LiteralClient(api_key="your_api_key_here")
# Access the API's methods
print(literalai_client.api)
```

<a id="literalai.api.__init__.LiteralAPI.get_users" />

#### get\_users

```python theme={null}
def get_users(first: Optional[int] = None,
              after: Optional[str] = None,
              before: Optional[str] = None,
              filters: Optional[users_filters] = None)
```

Retrieves a list of users based on pagination and optional filters.

**Arguments**:

<ResponseField name="first" type="Optional[int]">The number of users to retrieve.</ResponseField>
<ResponseField name="after" type="Optional[str]">A cursor for use in pagination, fetching records after this cursor.</ResponseField>
<ResponseField name="before" type="Optional[str]">A cursor for use in pagination, fetching records before this cursor.</ResponseField>

* `filters` *Optional\[users\_filters]* - Filters to apply to the user query.

**Returns**:

<ResponseField name="Dict">A dictionary containing the queried user data.</ResponseField>

<a id="literalai.api.__init__.LiteralAPI.get_user" />

#### get\_user

```python theme={null}
def get_user(id: Optional[str] = None, identifier: Optional[str] = None)
```

Retrieves a user based on the provided ID or identifier.

**Arguments**:

<ResponseField name="id" type="Optional[str]">The unique ID of the user.</ResponseField>
<ResponseField name="identifier" type="Optional[str]">A unique identifier for the user, such as a username or email.</ResponseField>

**Returns**:

The user data as returned by the GraphQL helper function.

<a id="literalai.api.__init__.LiteralAPI.create_user" />

#### create\_user

```python theme={null}
def create_user(identifier: str, metadata: Optional[Dict] = None)
```

Creates a new user with the specified identifier and optional metadata.

**Arguments**:

<ResponseField name="identifier" type="str">A unique identifier for the user, such as a username or email.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Additional data associated with the user.</ResponseField>

**Returns**:

The result of the GraphQL call to create a user.

<a id="literalai.api.__init__.LiteralAPI.update_user" />

#### update\_user

```python theme={null}
def update_user(id: str,
                identifier: Optional[str] = None,
                metadata: Optional[Dict] = None)
```

Updates an existing user identified by the given ID, with optional new identifier and metadata.

**Arguments**:

<ResponseField name="id" type="str">The unique ID of the user to update.</ResponseField>
<ResponseField name="identifier" type="Optional[str]">A new identifier for the user, such as a username or email.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">New or updated metadata for the user.</ResponseField>

**Returns**:

The result of the GraphQL call to update the user.

<a id="literalai.api.__init__.LiteralAPI.delete_user" />

#### delete\_user

```python theme={null}
def delete_user(id: str)
```

Deletes a user identified by the given ID.

**Arguments**:

<ResponseField name="id" type="str">The unique ID of the user to delete.</ResponseField>

**Returns**:

The result of the GraphQL call to delete the user.

<a id="literalai.api.__init__.LiteralAPI.get_or_create_user" />

#### get\_or\_create\_user

```python theme={null}
def get_or_create_user(identifier: str, metadata: Optional[Dict] = None)
```

Retrieves a user by their identifier, or creates a new user if they do not exist.

**Arguments**:

<ResponseField name="identifier" type="str">The identifier of the user to retrieve or create.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Metadata to associate with the user if they are created.</ResponseField>

**Returns**:

The existing or newly created user data.

<a id="literalai.api.__init__.LiteralAPI.get_threads" />

#### get\_threads

```python theme={null}
def get_threads(first: Optional[int] = None,
                after: Optional[str] = None,
                before: Optional[str] = None,
                filters: Optional[threads_filters] = None,
                order_by: Optional[threads_order_by] = None,
                step_types_to_keep: Optional[List[StepType]] = None)
```

Fetches a list of threads based on pagination and optional filters.

**Arguments**:

<ResponseField name="first" type="Optional[int]">Number of threads to fetch.</ResponseField>
<ResponseField name="after" type="Optional[str]">Cursor for pagination, fetch threads after this cursor.</ResponseField>
<ResponseField name="before" type="Optional[str]">Cursor for pagination, fetch threads before this cursor.</ResponseField>

* `filters` *Optional\[threads\_filters]* - Filters to apply on the threads query.
* `order_by` *Optional\[threads\_order\_by]* - Order by clause for threads.
  step\_types\_to\_keep (Optional\[List\[StepType]]) : If set, only steps of the corresponding types
  will be returned

**Returns**:

A list of threads that match the criteria.

<a id="literalai.api.__init__.LiteralAPI.list_threads" />

#### list\_threads

```python theme={null}
def list_threads(first: Optional[int] = None,
                 after: Optional[str] = None,
                 before: Optional[str] = None,
                 filters: Optional[threads_filters] = None,
                 order_by: Optional[threads_order_by] = None)
```

Lists threads based on pagination and optional filters, similar to get\_threads but may include additional processing.

**Arguments**:

<ResponseField name="first" type="Optional[int]">Number of threads to list.</ResponseField>
<ResponseField name="after" type="Optional[str]">Cursor for pagination, list threads after this cursor.</ResponseField>
<ResponseField name="before" type="Optional[str]">Cursor for pagination, list threads before this cursor.</ResponseField>

* `filters` *Optional\[threads\_filters]* - Filters to apply on the threads listing.
* `order_by` *Optional\[threads\_order\_by]* - Order by clause for threads.

**Returns**:

A list of threads that match the criteria.

<a id="literalai.api.__init__.LiteralAPI.get_thread" />

#### get\_thread

```python theme={null}
def get_thread(id: str)
```

Retrieves a single thread by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the thread.</ResponseField>

**Returns**:

The thread corresponding to the provided ID.

<a id="literalai.api.__init__.LiteralAPI.create_thread" />

#### create\_thread

```python theme={null}
def create_thread(name: Optional[str] = None,
                  metadata: Optional[Dict] = None,
                  participant_id: Optional[str] = None,
                  tags: Optional[List[str]] = None)
```

Creates a new thread with the specified details.

**Arguments**:

<ResponseField name="name" type="Optional[str]">Name of the thread.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Metadata associated with the thread.</ResponseField>
<ResponseField name="participant_id" type="Optional[str]">Identifier for the participant.</ResponseField>
<ResponseField name="tags" type="Optional[List[str]]">List of tags associated with the thread.</ResponseField>

**Returns**:

The newly created thread.

<a id="literalai.api.__init__.LiteralAPI.upsert_thread" />

#### upsert\_thread

```python theme={null}
def upsert_thread(id: str,
                  name: Optional[str] = None,
                  metadata: Optional[Dict] = None,
                  participant_id: Optional[str] = None,
                  tags: Optional[List[str]] = None)
```

Updates an existing thread or creates a new one if it does not exist.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the thread.</ResponseField>
<ResponseField name="name" type="Optional[str]">Name of the thread.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Metadata associated with the thread.</ResponseField>
<ResponseField name="participant_id" type="Optional[str]">Identifier for the participant.</ResponseField>
<ResponseField name="tags" type="Optional[List[str]]">List of tags associated with the thread.</ResponseField>

**Returns**:

The updated or newly created thread.

<a id="literalai.api.__init__.LiteralAPI.update_thread" />

#### update\_thread

```python theme={null}
def update_thread(id: str,
                  name: Optional[str] = None,
                  metadata: Optional[Dict] = None,
                  participant_id: Optional[str] = None,
                  tags: Optional[List[str]] = None)
```

Updates the specified details of an existing thread.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the thread to update.</ResponseField>
<ResponseField name="name" type="Optional[str]">New name of the thread.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">New metadata for the thread.</ResponseField>
<ResponseField name="participant_id" type="Optional[str]">New identifier for the participant.</ResponseField>
<ResponseField name="tags" type="Optional[List[str]]">New list of tags for the thread.</ResponseField>

**Returns**:

The updated thread.

<a id="literalai.api.__init__.LiteralAPI.delete_thread" />

#### delete\_thread

```python theme={null}
def delete_thread(id: str)
```

Deletes a thread identified by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the thread to delete.</ResponseField>

**Returns**:

The result of the deletion operation.

<a id="literalai.api.__init__.LiteralAPI.create_score" />

#### create\_score

```python theme={null}
def create_score(name: str,
                 value: float,
                 type: ScoreType,
                 step_id: Optional[str] = None,
                 generation_id: Optional[str] = None,
                 dataset_experiment_item_id: Optional[str] = None,
                 comment: Optional[str] = None,
                 tags: Optional[List[str]] = None)
```

Creates a single score in the database.

**Arguments**:

<ResponseField name="name" type="str">The name of the score.</ResponseField>
<ResponseField name="value" type="float">The numerical value of the score.</ResponseField>
<ResponseField name="type" type="ScoreType">The type of the score.</ResponseField>
<ResponseField name="step_id" type="Optional[str]">The ID of the step associated with the score.</ResponseField>
<ResponseField name="generation_id" type="Optional[str]">The ID of the generation associated with the score.</ResponseField>
<ResponseField name="dataset_experiment_item_id" type="Optional[str]">The ID of the dataset experiment item associated with the score.</ResponseField>
<ResponseField name="comment" type="Optional[str]">An optional comment about the score.</ResponseField>
<ResponseField name="tags" type="Optional[List[str]]">Optional tags associated with the score.</ResponseField>

**Returns**:

The created Score object.

<a id="literalai.api.__init__.LiteralAPI.update_score" />

#### update\_score

```python theme={null}
def update_score(id: str, update_params: ScoreUpdate)
```

Updates a score identified by its ID with new parameters.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the score to update.</ResponseField>
<ResponseField name="update_params" type="ScoreUpdate">A dictionary of parameters to update in the score.</ResponseField>

**Returns**:

The result of the update operation.

<a id="literalai.api.__init__.LiteralAPI.delete_score" />

#### delete\_score

```python theme={null}
def delete_score(id: str)
```

Deletes a score identified by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the score to delete.</ResponseField>

**Returns**:

The result of the deletion operation.

<a id="literalai.api.__init__.LiteralAPI.upload_file" />

#### upload\_file

```python theme={null}
def upload_file(content: Union[bytes, str],
                thread_id: Optional[str] = None,
                mime: Optional[str] = "application/octet-stream") -> Dict
```

Uploads a file to the server.

**Arguments**:

<ResponseField name="content" type="Union[bytes, str]">The content of the file to upload.</ResponseField>
<ResponseField name="thread_id" type="Optional[str]">The ID of the thread associated with the file.</ResponseField>
<ResponseField name="mime" type="Optional[str]">The MIME type of the file. Defaults to 'application/octet-stream'.</ResponseField>

**Returns**:

<ResponseField name="Dict">A dictionary containing the object key and URL of the uploaded file, or None values if the upload fails.</ResponseField>

<a id="literalai.api.__init__.LiteralAPI.create_attachment" />

#### create\_attachment

```python theme={null}
def create_attachment(thread_id: Optional[str] = None,
                      step_id: Optional[str] = None,
                      id: Optional[str] = None,
                      metadata: Optional[Dict] = None,
                      mime: Optional[str] = None,
                      name: Optional[str] = None,
                      object_key: Optional[str] = None,
                      url: Optional[str] = None,
                      content: Optional[Union[bytes, str]] = None,
                      path: Optional[str] = None) -> "Attachment"
```

Creates an attachment associated with a thread and step, potentially uploading file content.

**Arguments**:

<ResponseField name="thread_id" type="str">The ID of the thread to which the attachment is linked.</ResponseField>
<ResponseField name="step_id" type="str">The ID of the step to which the attachment is linked.</ResponseField>
<ResponseField name="id" type="Optional[str]">The ID of the attachment, if updating an existing one.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Metadata associated with the attachment.</ResponseField>
<ResponseField name="mime" type="Optional[str]">MIME type of the file, if content is provided.</ResponseField>
<ResponseField name="name" type="Optional[str]">Name of the attachment.</ResponseField>
<ResponseField name="object_key" type="Optional[str]">Object key of the uploaded file, if already known.</ResponseField>
<ResponseField name="url" type="Optional[str]">URL of the uploaded file, if already known.</ResponseField>
<ResponseField name="content" type="Optional[Union[bytes, str]]">File content to upload.</ResponseField>
<ResponseField name="path" type="Optional[str]">Path where the file should be stored.</ResponseField>

**Returns**:

<ResponseField name="literalai.observability.step.Attachment">The created or updated attachment object.</ResponseField>

<a id="literalai.api.__init__.LiteralAPI.update_attachment" />

#### update\_attachment

```python theme={null}
def update_attachment(id: str, update_params: AttachmentUpload)
```

Updates an existing attachment with new parameters.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the attachment to update.</ResponseField>
<ResponseField name="update_params" type="AttachmentUpload">The parameters to update in the attachment.</ResponseField>

**Returns**:

The result of the update operation.

<a id="literalai.api.__init__.LiteralAPI.get_attachment" />

#### get\_attachment

```python theme={null}
def get_attachment(id: str)
```

Retrieves an attachment by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the attachment to retrieve.</ResponseField>

**Returns**:

The attachment data as returned by the GraphQL helper function.

<a id="literalai.api.__init__.LiteralAPI.delete_attachment" />

#### delete\_attachment

```python theme={null}
def delete_attachment(id: str)
```

Deletes an attachment identified by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the attachment to delete.</ResponseField>

**Returns**:

The result of the deletion operation.

<a id="literalai.api.__init__.LiteralAPI.create_step" />

#### create\_step

```python theme={null}
def create_step(thread_id: Optional[str] = None,
                type: Optional[StepType] = "undefined",
                start_time: Optional[str] = None,
                end_time: Optional[str] = None,
                input: Optional[Dict] = None,
                output: Optional[Dict] = None,
                metadata: Optional[Dict] = None,
                parent_id: Optional[str] = None,
                name: Optional[str] = None,
                tags: Optional[List[str]] = None,
                root_run_id: Optional[str] = None)
```

Creates a new step with the specified parameters.

**Arguments**:

<ResponseField name="thread_id" type="Optional[str]">The ID of the thread this step is associated with.</ResponseField>
<ResponseField name="type" type="Optional[StepType]">The type of the step, defaults to "undefined".</ResponseField>
<ResponseField name="start_time" type="Optional[str]">The start time of the step.</ResponseField>
<ResponseField name="end_time" type="Optional[str]">The end time of the step.</ResponseField>
<ResponseField name="input" type="Optional[Dict]">Input data for the step.</ResponseField>
<ResponseField name="output" type="Optional[Dict]">Output data from the step.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Metadata associated with the step.</ResponseField>
<ResponseField name="parent_id" type="Optional[str]">The ID of the parent step, if any.</ResponseField>
<ResponseField name="name" type="Optional[str]">The name of the step.</ResponseField>
<ResponseField name="tags" type="Optional[List[str]]">Tags associated with the step.</ResponseField>
<ResponseField name="root_run_id" type="Optional[str]">The ID of the root run, if any.</ResponseField>

**Returns**:

The result of the GraphQL helper function for creating a step.

<a id="literalai.api.__init__.LiteralAPI.update_step" />

#### update\_step

```python theme={null}
def update_step(id: str,
                type: Optional[StepType] = None,
                input: Optional[str] = None,
                output: Optional[str] = None,
                metadata: Optional[Dict] = None,
                name: Optional[str] = None,
                tags: Optional[List[str]] = None,
                start_time: Optional[str] = None,
                end_time: Optional[str] = None,
                parent_id: Optional[str] = None)
```

Updates an existing step identified by its ID with new parameters.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the step to update.</ResponseField>
<ResponseField name="type" type="Optional[StepType]">The type of the step.</ResponseField>
<ResponseField name="input" type="Optional[str]">Input data for the step.</ResponseField>
<ResponseField name="output" type="Optional[str]">Output data from the step.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Metadata associated with the step.</ResponseField>
<ResponseField name="name" type="Optional[str]">The name of the step.</ResponseField>
<ResponseField name="tags" type="Optional[List[str]]">Tags associated with the step.</ResponseField>
<ResponseField name="start_time" type="Optional[str]">The start time of the step.</ResponseField>
<ResponseField name="end_time" type="Optional[str]">The end time of the step.</ResponseField>
<ResponseField name="parent_id" type="Optional[str]">The ID of the parent step, if any.</ResponseField>

**Returns**:

The result of the GraphQL helper function for updating a step.

<a id="literalai.api.__init__.LiteralAPI.get_steps" />

#### get\_steps

```python theme={null}
def get_steps(
        first: Optional[int] = None,
        after: Optional[str] = None,
        before: Optional[str] = None,
        filters: Optional[steps_filters] = None,
        order_by: Optional[steps_order_by] = None) -> PaginatedResponse[Step]
```

Fetches a list of steps based on pagination and optional filters.

**Arguments**:

<ResponseField name="first" type="Optional[int]">Number of steps to fetch.</ResponseField>
<ResponseField name="after" type="Optional[str]">Cursor for pagination, fetch steps after this cursor.</ResponseField>
<ResponseField name="before" type="Optional[str]">Cursor for pagination, fetch steps before this cursor.</ResponseField>

* `filters` *Optional\[steps\_filters]* - Filters to apply on the steps query.
* `order_by` *Optional\[steps\_order\_by]* - Order by clause for steps.

**Returns**:

A list of steps that match the criteria.

<a id="literalai.api.__init__.LiteralAPI.get_step" />

#### get\_step

```python theme={null}
def get_step(id: str)
```

Retrieves a step by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the step to retrieve.</ResponseField>

**Returns**:

The step data as returned by the GraphQL helper function.

<a id="literalai.api.__init__.LiteralAPI.delete_step" />

#### delete\_step

```python theme={null}
def delete_step(id: str)
```

Deletes a step identified by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the step to delete.</ResponseField>

**Returns**:

The result of the deletion operation.

<a id="literalai.api.__init__.LiteralAPI.send_steps" />

#### send\_steps

```python theme={null}
def send_steps(steps: List[Union[StepDict, "Step"]])
```

Sends a list of steps to be processed.

**Arguments**:

<ResponseField name="steps" type="List[Union[StepDict, Step]]">A list of steps or step dictionaries to send.</ResponseField>

**Returns**:

The result of the GraphQL helper function for sending steps.

<a id="literalai.api.__init__.LiteralAPI.get_generations" />

#### get\_generations

```python theme={null}
def get_generations(first: Optional[int] = None,
                    after: Optional[str] = None,
                    before: Optional[str] = None,
                    filters: Optional[generations_filters] = None,
                    order_by: Optional[generations_order_by] = None)
```

Fetches a list of generations based on pagination and optional filters.

**Arguments**:

<ResponseField name="first" type="Optional[int]">The number of generations to retrieve.</ResponseField>
<ResponseField name="after" type="Optional[str]">A cursor for use in pagination, fetching records after this cursor.</ResponseField>
<ResponseField name="before" type="Optional[str]">A cursor for use in pagination, fetching records before this cursor.</ResponseField>

* `filters` *Optional\[generations\_filters]* - Filters to apply to the generations query.
* `order_by` *Optional\[generations\_order\_by]* - Order by clause for generations.

**Returns**:

A list of generations that match the criteria.

<a id="literalai.api.__init__.LiteralAPI.create_generation" />

#### create\_generation

```python theme={null}
def create_generation(generation: Union[ChatGeneration, CompletionGeneration])
```

Creates a new generation, either a chat or completion type.

```py theme={null}
from literalai.observability.generation import ChatGeneration
from literalai import LiteralClient

literalai_client = LiteralClient(api_key=)

example_generation = ChatGeneration(
    messages=[
        {
            "role": "user",
            "content": "Hello, how can I help you today?"
        },
    ],
    message_completion={
        "role": "assistant",
        "content": "Sure, I can help with that. What do you need to know?"
    },
    model="gpt-4o-mini",
    provider="OpenAI"
)

literalai_client.api.create_generation(example_generation)
```

**Arguments**:

<ResponseField name="generation" type="Union[ChatGeneration, CompletionGeneration]">The generation data to create.</ResponseField>

**Returns**:

The result of the creation operation.

<a id="literalai.api.__init__.LiteralAPI.create_dataset" />

#### create\_dataset

```python theme={null}
def create_dataset(name: str,
                   description: Optional[str] = None,
                   metadata: Optional[Dict] = None,
                   type: DatasetType = "key_value")
```

Creates a new dataset with the specified properties.

**Arguments**:

<ResponseField name="name" type="str">The name of the dataset.</ResponseField>
<ResponseField name="description" type="Optional[str]">A description of the dataset.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Additional metadata for the dataset.</ResponseField>
<ResponseField name="type" type="DatasetType">The type of the dataset, defaults to "key\_value".</ResponseField>

**Returns**:

The result of the dataset creation operation.

<a id="literalai.api.__init__.LiteralAPI.get_dataset" />

#### get\_dataset

```python theme={null}
def get_dataset(id: Optional[str] = None,
                name: Optional[str] = None) -> Optional[Dataset]
```

Retrieves a dataset by its ID or name.

**Arguments**:

<ResponseField name="id" type="Optional[str]">The unique identifier of the dataset.</ResponseField>
<ResponseField name="name" type="Optional[str]">The name of the dataset.</ResponseField>

**Returns**:

The dataset data as returned by the REST helper function.

<a id="literalai.api.__init__.LiteralAPI.update_dataset" />

#### update\_dataset

```python theme={null}
def update_dataset(id: str,
                   name: Optional[str] = None,
                   description: Optional[str] = None,
                   metadata: Optional[Dict] = None)
```

Updates an existing dataset identified by its ID with new properties.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the dataset to update.</ResponseField>
<ResponseField name="name" type="Optional[str]">A new name for the dataset.</ResponseField>
<ResponseField name="description" type="Optional[str]">A new description for the dataset.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">New or updated metadata for the dataset.</ResponseField>

**Returns**:

The result of the dataset update operation.

<a id="literalai.api.__init__.LiteralAPI.delete_dataset" />

#### delete\_dataset

```python theme={null}
def delete_dataset(id: str)
```

Deletes a dataset identified by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the dataset to delete.</ResponseField>

**Returns**:

The result of the deletion operation.

<a id="literalai.api.__init__.LiteralAPI.create_experiment" />

#### create\_experiment

```python theme={null}
def create_experiment(name: str,
                      dataset_id: Optional[str] = None,
                      prompt_id: Optional[str] = None,
                      params: Optional[Dict] = None) -> "DatasetExperiment"
```

Creates a new experiment associated with a specific dataset.

**Arguments**:

<ResponseField name="name" type="str">The name of the experiment.</ResponseField>
<ResponseField name="dataset_id" type="Optional[str]">The unique identifier of the dataset.</ResponseField>
<ResponseField name="prompt_id" type="Optional[str]">The identifier of the prompt associated with the experiment.</ResponseField>
<ResponseField name="params" type="Optional[Dict]">Additional parameters for the experiment.</ResponseField>

**Returns**:

<ResponseField name="DatasetExperiment">The newly created experiment object.</ResponseField>

<a id="literalai.api.__init__.LiteralAPI.create_experiment_item" />

#### create\_experiment\_item

```python theme={null}
def create_experiment_item(
        experiment_item: DatasetExperimentItem) -> DatasetExperimentItem
```

Creates an experiment item within an existing experiment.

**Arguments**:

<ResponseField name="experiment_item" type="DatasetExperimentItem">The experiment item to be created, containing all necessary data.</ResponseField>

**Returns**:

<ResponseField name="DatasetExperimentItem">The newly created experiment item with scores attached.</ResponseField>

<a id="literalai.api.__init__.LiteralAPI.create_dataset_item" />

#### create\_dataset\_item

```python theme={null}
def create_dataset_item(dataset_id: str,
                        input: Dict,
                        expected_output: Optional[Dict] = None,
                        metadata: Optional[Dict] = None)
```

Creates a new dataset item with the specified properties.

**Arguments**:

<ResponseField name="dataset_id" type="str">The unique identifier of the dataset.</ResponseField>
<ResponseField name="input" type="Dict">The input data for the dataset item.</ResponseField>
<ResponseField name="expected_output" type="Optional[Dict]">The expected output data for the dataset item.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Additional metadata for the dataset item.</ResponseField>

**Returns**:

<ResponseField name="Dict">The result of the dataset item creation operation.</ResponseField>

<a id="literalai.api.__init__.LiteralAPI.get_dataset_item" />

#### get\_dataset\_item

```python theme={null}
def get_dataset_item(id: str)
```

Retrieves a dataset item by its unique identifier.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the dataset item to retrieve.</ResponseField>

**Returns**:

<ResponseField name="Dict">The dataset item data.</ResponseField>

<a id="literalai.api.__init__.LiteralAPI.delete_dataset_item" />

#### delete\_dataset\_item

```python theme={null}
def delete_dataset_item(id: str)
```

Deletes a dataset item by its unique identifier.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the dataset item to delete.</ResponseField>

**Returns**:

<ResponseField name="Dict">The result of the dataset item deletion operation.</ResponseField>

<a id="literalai.api.__init__.LiteralAPI.add_step_to_dataset" />

#### add\_step\_to\_dataset

```python theme={null}
def add_step_to_dataset(dataset_id: str,
                        step_id: str,
                        metadata: Optional[Dict] = None)
```

Adds a step to a dataset.

**Arguments**:

<ResponseField name="dataset_id" type="str">The unique identifier of the dataset.</ResponseField>
<ResponseField name="step_id" type="str">The unique identifier of the step to add.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Additional metadata for the step being added.</ResponseField>

**Returns**:

<ResponseField name="Dict">The result of adding the step to the dataset.</ResponseField>

<a id="literalai.api.__init__.LiteralAPI.add_generation_to_dataset" />

#### add\_generation\_to\_dataset

```python theme={null}
def add_generation_to_dataset(dataset_id: str,
                              generation_id: str,
                              metadata: Optional[Dict] = None)
```

Adds a generation to a dataset.

**Arguments**:

<ResponseField name="dataset_id" type="str">The unique identifier of the dataset.</ResponseField>
<ResponseField name="generation_id" type="str">The unique identifier of the generation to add.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Additional metadata for the generation being added.</ResponseField>

**Returns**:

<ResponseField name="Dict">The result of adding the generation to the dataset.</ResponseField>

<a id="literalai.api.__init__.LiteralAPI.get_or_create_prompt_lineage" />

#### get\_or\_create\_prompt\_lineage

```python theme={null}
def get_or_create_prompt_lineage(name: str, description: Optional[str] = None)
```

Creates a prompt lineage with the specified name and optional description.
If the prompt lineage with that name already exists, it is returned.

**Arguments**:

<ResponseField name="name" type="str">The name of the prompt lineage.</ResponseField>
<ResponseField name="description" type="Optional[str]">An optional description of the prompt lineage.</ResponseField>

**Returns**:

<ResponseField name="Dict">The result of the prompt lineage creation operation.</ResponseField>

<a id="literalai.api.__init__.LiteralAPI.get_or_create_prompt" />

#### get\_or\_create\_prompt

```python theme={null}
def get_or_create_prompt(name: str,
                         template_messages: List[GenerationMessage],
                         settings: Optional[ProviderSettings] = None,
                         tools: Optional[List[Dict]] = None) -> Prompt
```

A `Prompt` is fully defined by its `name`, `template_messages`, `settings` and tools.
If a prompt already exists for the given arguments, it is returned.
Otherwise, a new prompt is created.

**Arguments**:

<ResponseField name="name" type="str">The name of the prompt to retrieve or create.</ResponseField>
<ResponseField name="template_messages" type="List[GenerationMessage]">A list of template messages for the prompt.</ResponseField>
<ResponseField name="settings" type="Optional[Dict]">Optional settings for the prompt.</ResponseField>
<ResponseField name="tools" type="Optional[List[Dict]]">Optional tool options for the model</ResponseField>

**Returns**:

<ResponseField name="Prompt">The prompt that was retrieved or created.</ResponseField>

<a id="literalai.api.__init__.LiteralAPI.get_prompt" />

#### get\_prompt

```python theme={null}
def get_prompt(id: Optional[str] = None,
               name: Optional[str] = None,
               version: Optional[int] = None) -> Prompt
```

Gets a prompt either by:

* `id`
* or `name` and (optional) `version`

Either the `id` or the `name` must be provided.
If both are provided, the `id` is used.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the prompt to retrieve.</ResponseField>
<ResponseField name="name" type="str">The name of the prompt to retrieve.</ResponseField>
<ResponseField name="version" type="Optional[int]">The version number of the prompt to retrieve.</ResponseField>

**Returns**:

<ResponseField name="Prompt">The prompt with the given identifier or name.</ResponseField>

<a id="literalai.api.__init__.LiteralAPI.get_prompt_ab_testing" />

#### get\_prompt\_ab\_testing

```python theme={null}
def get_prompt_ab_testing(name: str) -> List[PromptRollout]
```

Get the A/B testing configuration for a prompt lineage.

**Arguments**:

<ResponseField name="name" type="str">The name of the prompt lineage.</ResponseField>

**Returns**:

List\[PromptRollout]

<a id="literalai.api.__init__.LiteralAPI.update_prompt_ab_testing" />

#### update\_prompt\_ab\_testing

```python theme={null}
def update_prompt_ab_testing(name: str, rollouts: List[PromptRollout]) -> Dict
```

Update the A/B testing configuration for a prompt lineage.

**Arguments**:

<ResponseField name="name" type="str">The name of the prompt lineage.</ResponseField>
<ResponseField name="rollouts" type="List[PromptRollout]">The percentage rollout for each prompt version.</ResponseField>

**Returns**:

Dict

<a id="literalai.api.__init__.LiteralAPI.get_my_project_id" />

#### get\_my\_project\_id

```python theme={null}
def get_my_project_id()
```

Retrieves the projectId associated to the API key.

**Returns**:

The projectId associated to the API key.

<a id="literalai.api.__init__.AsyncLiteralAPI" />

## AsyncLiteralAPI

```python theme={null}
class AsyncLiteralAPI(BaseLiteralAPI)
```

```python theme={null}
from literalai import AsyncLiteralClient
# Initialize the client
async_literalai_client = AsyncLiteralClient(api_key="your_api_key_here")
# Access the API's methods
print(async_literalai_client.api)
```

<a id="literalai.api.__init__.AsyncLiteralAPI.get_users" />

#### get\_users

```python theme={null}
async def get_users(first: Optional[int] = None,
                    after: Optional[str] = None,
                    before: Optional[str] = None,
                    filters: Optional[users_filters] = None)
```

Asynchronously fetches a list of users based on pagination and optional filters.

**Arguments**:

<ResponseField name="first" type="Optional[int]">The number of users to retrieve.</ResponseField>
<ResponseField name="after" type="Optional[str]">A cursor for use in pagination, fetching records after this cursor.</ResponseField>
<ResponseField name="before" type="Optional[str]">A cursor for use in pagination, fetching records before this cursor.</ResponseField>

* `filters` *Optional\[users\_filters]* - Filters to apply to the user query.

**Returns**:

The result of the GraphQL helper function for fetching users.

<a id="literalai.api.__init__.AsyncLiteralAPI.get_user" />

#### get\_user

```python theme={null}
async def get_user(id: Optional[str] = None, identifier: Optional[str] = None)
```

Asynchronously retrieves a user by ID or identifier.

**Arguments**:

<ResponseField name="id" type="Optional[str]">The unique identifier of the user to retrieve.</ResponseField>
<ResponseField name="identifier" type="Optional[str]">An alternative identifier for the user.</ResponseField>

**Returns**:

The result of the GraphQL helper function for fetching a user.

<a id="literalai.api.__init__.AsyncLiteralAPI.create_user" />

#### create\_user

```python theme={null}
async def create_user(identifier: str, metadata: Optional[Dict] = None)
```

Asynchronously creates a new user with the specified identifier and optional metadata.

**Arguments**:

<ResponseField name="identifier" type="str">The identifier for the new user.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Additional metadata for the user.</ResponseField>

**Returns**:

The result of the GraphQL helper function for creating a user.

<a id="literalai.api.__init__.AsyncLiteralAPI.update_user" />

#### update\_user

```python theme={null}
async def update_user(id: str,
                      identifier: Optional[str] = None,
                      metadata: Optional[Dict] = None)
```

Asynchronously updates an existing user identified by ID with new identifier and/or metadata.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the user to update.</ResponseField>
<ResponseField name="identifier" type="Optional[str]">New identifier for the user.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">New metadata for the user.</ResponseField>

**Returns**:

The result of the GraphQL helper function for updating a user.

<a id="literalai.api.__init__.AsyncLiteralAPI.delete_user" />

#### delete\_user

```python theme={null}
async def delete_user(id: str)
```

Asynchronously deletes a user identified by ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the user to delete.</ResponseField>

**Returns**:

The result of the GraphQL helper function for deleting a user.

<a id="literalai.api.__init__.AsyncLiteralAPI.get_or_create_user" />

#### get\_or\_create\_user

```python theme={null}
async def get_or_create_user(identifier: str, metadata: Optional[Dict] = None)
```

Asynchronously retrieves a user by identifier or creates a new one if it does not exist.

**Arguments**:

<ResponseField name="identifier" type="str">The identifier of the user to retrieve or create.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Metadata for the user if creation is necessary.</ResponseField>

**Returns**:

The existing or newly created user.

<a id="literalai.api.__init__.AsyncLiteralAPI.get_threads" />

#### get\_threads

```python theme={null}
async def get_threads(first: Optional[int] = None,
                      after: Optional[str] = None,
                      before: Optional[str] = None,
                      filters: Optional[threads_filters] = None,
                      order_by: Optional[threads_order_by] = None,
                      step_types_to_keep: Optional[List[StepType]] = None)
```

Asynchronously fetches a list of threads based on pagination and optional filters and ordering.

**Arguments**:

<ResponseField name="first" type="Optional[int]">The number of threads to retrieve.</ResponseField>
<ResponseField name="after" type="Optional[str]">A cursor for use in pagination, fetching records after this cursor.</ResponseField>
<ResponseField name="before" type="Optional[str]">A cursor for use in pagination, fetching records before this cursor.</ResponseField>

* `filters` *Optional\[threads\_filters]* - Filters to apply to the thread query.
* `order_by` *Optional\[threads\_order\_by]* - Ordering criteria for the threads.
  step\_types\_to\_keep (Optional\[List\[StepType]]) : If set, only steps of the corresponding types
  will be returned

**Returns**:

The result of the GraphQL helper function for fetching threads.

<a id="literalai.api.__init__.AsyncLiteralAPI.list_threads" />

#### list\_threads

```python theme={null}
async def list_threads(first: Optional[int] = None,
                       after: Optional[str] = None,
                       before: Optional[str] = None,
                       filters: Optional[threads_filters] = None,
                       order_by: Optional[threads_order_by] = None)
```

Asynchronously lists threads based on pagination and optional filters and ordering, similar to `get_threads`.

**Arguments**:

<ResponseField name="first" type="Optional[int]">The number of threads to list.</ResponseField>
<ResponseField name="after" type="Optional[str]">A cursor for use in pagination, fetching records after this cursor.</ResponseField>
<ResponseField name="before" type="Optional[str]">A cursor for use in pagination, fetching records before this cursor.</ResponseField>

* `filters` *Optional\[threads\_filters]* - Filters to apply to the thread query.
* `order_by` *Optional\[threads\_order\_by]* - Ordering criteria for the threads.

**Returns**:

The result of the GraphQL helper function for listing threads.

<a id="literalai.api.__init__.AsyncLiteralAPI.get_thread" />

#### get\_thread

```python theme={null}
async def get_thread(id: str)
```

Asynchronously retrieves a thread by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the thread to retrieve.</ResponseField>

**Returns**:

The result of the GraphQL helper function for fetching a thread.

<a id="literalai.api.__init__.AsyncLiteralAPI.create_thread" />

#### create\_thread

```python theme={null}
async def create_thread(name: Optional[str] = None,
                        metadata: Optional[Dict] = None,
                        participant_id: Optional[str] = None,
                        tags: Optional[List[str]] = None)
```

Asynchronously creates a new thread with specified details.

**Arguments**:

<ResponseField name="name" type="Optional[str]">The name of the thread.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Metadata associated with the thread.</ResponseField>
<ResponseField name="participant_id" type="Optional[str]">Identifier for the participant associated with the thread.</ResponseField>
<ResponseField name="tags" type="Optional[List[str]]">Tags associated with the thread.</ResponseField>

**Returns**:

The result of the GraphQL helper function for creating a thread.

<a id="literalai.api.__init__.AsyncLiteralAPI.upsert_thread" />

#### upsert\_thread

```python theme={null}
async def upsert_thread(id: str,
                        name: Optional[str] = None,
                        metadata: Optional[Dict] = None,
                        participant_id: Optional[str] = None,
                        tags: Optional[List[str]] = None)
```

Asynchronously updates or inserts a thread based on the provided ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the thread to upsert.</ResponseField>
<ResponseField name="name" type="Optional[str]">The name of the thread.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Metadata associated with the thread.</ResponseField>
<ResponseField name="participant_id" type="Optional[str]">Identifier for the participant associated with the thread.</ResponseField>
<ResponseField name="tags" type="Optional[List[str]]">Tags associated with the thread.</ResponseField>

**Returns**:

The result of the GraphQL helper function for upserting a thread.

<a id="literalai.api.__init__.AsyncLiteralAPI.update_thread" />

#### update\_thread

```python theme={null}
async def update_thread(id: str,
                        name: Optional[str] = None,
                        metadata: Optional[Dict] = None,
                        participant_id: Optional[str] = None,
                        tags: Optional[List[str]] = None)
```

Asynchronously updates an existing thread identified by ID with new details.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the thread to update.</ResponseField>
<ResponseField name="name" type="Optional[str]">New name of the thread.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">New metadata for the thread.</ResponseField>
<ResponseField name="participant_id" type="Optional[str]">New identifier for the participant.</ResponseField>
<ResponseField name="tags" type="Optional[List[str]]">New list of tags for the thread.</ResponseField>

**Returns**:

The result of the GraphQL helper function for updating a thread.

<a id="literalai.api.__init__.AsyncLiteralAPI.delete_thread" />

#### delete\_thread

```python theme={null}
async def delete_thread(id: str)
```

Asynchronously deletes a thread identified by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the thread to delete.</ResponseField>

**Returns**:

The result of the GraphQL helper function for deleting a thread.

<a id="literalai.api.__init__.AsyncLiteralAPI.get_scores" />

#### get\_scores

```python theme={null}
async def get_scores(first: Optional[int] = None,
                     after: Optional[str] = None,
                     before: Optional[str] = None,
                     filters: Optional[scores_filters] = None,
                     order_by: Optional[scores_order_by] = None)
```

Asynchronously fetches scores based on pagination and optional filters.

**Arguments**:

<ResponseField name="first" type="Optional[int]">The number of scores to retrieve.</ResponseField>
<ResponseField name="after" type="Optional[str]">A cursor for use in pagination, fetching records after this cursor.</ResponseField>
<ResponseField name="before" type="Optional[str]">A cursor for use in pagination, fetching records before this cursor.</ResponseField>

* `filters` *Optional\[scores\_filters]* - Filters to apply to the scores query.
* `order_by` *Optional\[scores\_order\_by]* - Ordering options for the scores.

**Returns**:

The result of the GraphQL helper function for fetching scores.

<a id="literalai.api.__init__.AsyncLiteralAPI.create_scores" />

#### create\_scores

```python theme={null}
async def create_scores(scores: List[ScoreDict])
```

Asynchronously creates multiple scores.

**Arguments**:

<ResponseField name="scores" type="List[literalai.observability.step.ScoreDict]">A list of dictionaries representing the scores to be created.</ResponseField>

**Returns**:

The result of the GraphQL helper function for creating scores.

<a id="literalai.api.__init__.AsyncLiteralAPI.create_score" />

#### create\_score

```python theme={null}
async def create_score(name: str,
                       value: float,
                       type: ScoreType,
                       step_id: Optional[str] = None,
                       generation_id: Optional[str] = None,
                       dataset_experiment_item_id: Optional[str] = None,
                       comment: Optional[str] = None,
                       tags: Optional[List[str]] = None)
```

Asynchronously creates a single score.

**Arguments**:

<ResponseField name="name" type="str">The name of the score.</ResponseField>
<ResponseField name="value" type="float">The numerical value of the score.</ResponseField>
<ResponseField name="type" type="ScoreType">The type of the score.</ResponseField>
<ResponseField name="step_id" type="Optional[str]">The ID of the step associated with the score.</ResponseField>
<ResponseField name="generation_id">Deprecated - use step\_id</ResponseField>
<ResponseField name="dataset_experiment_item_id" type="Optional[str]">The ID of the dataset experiment item associated with the score.</ResponseField>
<ResponseField name="comment" type="Optional[str]">A comment associated with the score.</ResponseField>
<ResponseField name="tags" type="Optional[List[str]]">A list of tags associated with the score.</ResponseField>

**Returns**:

The result of the GraphQL helper function for creating a score.

<a id="literalai.api.__init__.AsyncLiteralAPI.update_score" />

#### update\_score

```python theme={null}
async def update_score(id: str, update_params: ScoreUpdate)
```

Asynchronously updates a score identified by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the score to update.</ResponseField>
<ResponseField name="update_params" type="ScoreUpdate">A dictionary of parameters to update.</ResponseField>

**Returns**:

The result of the GraphQL helper function for updating a score.

<a id="literalai.api.__init__.AsyncLiteralAPI.delete_score" />

#### delete\_score

```python theme={null}
async def delete_score(id: str)
```

Asynchronously deletes a score identified by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the score to delete.</ResponseField>

**Returns**:

The result of the GraphQL helper function for deleting a score.

<a id="literalai.api.__init__.AsyncLiteralAPI.upload_file" />

#### upload\_file

```python theme={null}
async def upload_file(
        content: Union[bytes, str],
        thread_id: Optional[str] = None,
        mime: Optional[str] = "application/octet-stream") -> Dict
```

Asynchronously uploads a file to the server.

**Arguments**:

<ResponseField name="content" type="Union[bytes, str]">The content of the file to upload.</ResponseField>
<ResponseField name="thread_id" type="str">The ID of the thread associated with the file.</ResponseField>
<ResponseField name="mime" type="Optional[str]">The MIME type of the file.</ResponseField>

**Returns**:

A dictionary containing the object key and URL of the uploaded file.

<a id="literalai.api.__init__.AsyncLiteralAPI.create_attachment" />

#### create\_attachment

```python theme={null}
async def create_attachment(thread_id: str,
                            step_id: str,
                            id: Optional[str] = None,
                            metadata: Optional[Dict] = None,
                            mime: Optional[str] = None,
                            name: Optional[str] = None,
                            object_key: Optional[str] = None,
                            url: Optional[str] = None,
                            content: Optional[Union[bytes, str]] = None,
                            path: Optional[str] = None) -> "Attachment"
```

Asynchronously creates an attachment and uploads it if content is provided.

**Arguments**:

<ResponseField name="thread_id" type="str">The ID of the thread associated with the attachment.</ResponseField>
<ResponseField name="step_id" type="str">The ID of the step associated with the attachment.</ResponseField>
<ResponseField name="id" type="Optional[str]">An optional unique identifier for the attachment.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Optional metadata for the attachment.</ResponseField>
<ResponseField name="mime" type="Optional[str]">The MIME type of the attachment.</ResponseField>
<ResponseField name="name" type="Optional[str]">The name of the attachment.</ResponseField>
<ResponseField name="object_key" type="Optional[str]">The object key for the attachment if already uploaded.</ResponseField>
<ResponseField name="url" type="Optional[str]">The URL of the attachment if already uploaded.</ResponseField>
<ResponseField name="content" type="Optional[Union[bytes, str]]">The content of the attachment to upload.</ResponseField>
<ResponseField name="path" type="Optional[str]">The file path of the attachment if it is to be uploaded from a local file.</ResponseField>

**Returns**:

The attachment object created after the upload and creation process.

<a id="literalai.api.__init__.AsyncLiteralAPI.update_attachment" />

#### update\_attachment

```python theme={null}
async def update_attachment(id: str, update_params: AttachmentUpload)
```

Asynchronously updates an attachment identified by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the attachment to update.</ResponseField>
<ResponseField name="update_params" type="AttachmentUpload">A dictionary of parameters to update the attachment.</ResponseField>

**Returns**:

The result of the GraphQL helper function for updating an attachment.

<a id="literalai.api.__init__.AsyncLiteralAPI.get_attachment" />

#### get\_attachment

```python theme={null}
async def get_attachment(id: str)
```

Asynchronously retrieves an attachment by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the attachment to retrieve.</ResponseField>

**Returns**:

The result of the GraphQL helper function for fetching an attachment.

<a id="literalai.api.__init__.AsyncLiteralAPI.delete_attachment" />

#### delete\_attachment

```python theme={null}
async def delete_attachment(id: str)
```

Asynchronously deletes an attachment identified by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the attachment to delete.</ResponseField>

**Returns**:

The result of the GraphQL helper function for deleting an attachment.

<a id="literalai.api.__init__.AsyncLiteralAPI.create_step" />

#### create\_step

```python theme={null}
async def create_step(thread_id: Optional[str] = None,
                      type: Optional[StepType] = "undefined",
                      start_time: Optional[str] = None,
                      end_time: Optional[str] = None,
                      input: Optional[Dict] = None,
                      output: Optional[Dict] = None,
                      metadata: Optional[Dict] = None,
                      parent_id: Optional[str] = None,
                      name: Optional[str] = None,
                      tags: Optional[List[str]] = None,
                      root_run_id: Optional[str] = None)
```

Asynchronously creates a new step with the specified parameters.

**Arguments**:

<ResponseField name="thread_id" type="Optional[str]">The ID of the thread associated with the step.</ResponseField>
<ResponseField name="type" type="Optional[StepType]">The type of the step, defaults to "undefined".</ResponseField>
<ResponseField name="start_time" type="Optional[str]">The start time of the step.</ResponseField>
<ResponseField name="end_time" type="Optional[str]">The end time of the step.</ResponseField>
<ResponseField name="input" type="Optional[Dict]">Input data for the step.</ResponseField>
<ResponseField name="output" type="Optional[Dict]">Output data from the step.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Metadata associated with the step.</ResponseField>
<ResponseField name="parent_id" type="Optional[str]">The ID of the parent step, if any.</ResponseField>
<ResponseField name="name" type="Optional[str]">The name of the step.</ResponseField>
<ResponseField name="tags" type="Optional[List[str]]">Tags associated with the step.</ResponseField>
<ResponseField name="root_run_id" type="Optional[str]">The ID of the root run, if any.</ResponseField>

**Returns**:

The result of the GraphQL helper function for creating a step.

<a id="literalai.api.__init__.AsyncLiteralAPI.update_step" />

#### update\_step

```python theme={null}
async def update_step(id: str,
                      type: Optional[StepType] = None,
                      input: Optional[str] = None,
                      output: Optional[str] = None,
                      metadata: Optional[Dict] = None,
                      name: Optional[str] = None,
                      tags: Optional[List[str]] = None,
                      start_time: Optional[str] = None,
                      end_time: Optional[str] = None,
                      parent_id: Optional[str] = None)
```

Asynchronously updates an existing step identified by its ID with new parameters.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the step to update.</ResponseField>
<ResponseField name="type" type="Optional[StepType]">The type of the step.</ResponseField>
<ResponseField name="input" type="Optional[str]">Input data for the step.</ResponseField>
<ResponseField name="output" type="Optional[str]">Output data from the step.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Metadata associated with the step.</ResponseField>
<ResponseField name="name" type="Optional[str]">The name of the step.</ResponseField>
<ResponseField name="tags" type="Optional[List[str]]">Tags associated with the step.</ResponseField>
<ResponseField name="start_time" type="Optional[str]">The start time of the step.</ResponseField>
<ResponseField name="end_time" type="Optional[str]">The end time of the step.</ResponseField>
<ResponseField name="parent_id" type="Optional[str]">The ID of the parent step, if any.</ResponseField>

**Returns**:

The result of the GraphQL helper function for updating a step.

<a id="literalai.api.__init__.AsyncLiteralAPI.get_step" />

#### get\_step

```python theme={null}
async def get_step(id: str)
```

Asynchronously retrieves a step by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the step to retrieve.</ResponseField>

**Returns**:

The result of the GraphQL helper function for fetching a step.

<a id="literalai.api.__init__.AsyncLiteralAPI.delete_step" />

#### delete\_step

```python theme={null}
async def delete_step(id: str)
```

Asynchronously deletes a step identified by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the step to delete.</ResponseField>

**Returns**:

The result of the GraphQL helper function for deleting a step.

<a id="literalai.api.__init__.AsyncLiteralAPI.send_steps" />

#### send\_steps

```python theme={null}
async def send_steps(steps: List[Union[StepDict, "Step"]])
```

Asynchronously sends a list of steps to be processed.

**Arguments**:

<ResponseField name="steps" type="List[Union[StepDict, Step]]">A list of steps or step dictionaries to send.</ResponseField>

**Returns**:

The result of the GraphQL helper function for sending steps.

<a id="literalai.api.__init__.AsyncLiteralAPI.get_generations" />

#### get\_generations

```python theme={null}
async def get_generations(first: Optional[int] = None,
                          after: Optional[str] = None,
                          before: Optional[str] = None,
                          filters: Optional[generations_filters] = None,
                          order_by: Optional[generations_order_by] = None)
```

Asynchronously fetches a list of generations based on pagination and optional filters.

**Arguments**:

<ResponseField name="first" type="Optional[int]">The number of generations to retrieve.</ResponseField>
<ResponseField name="after" type="Optional[str]">A cursor for use in pagination, fetching records after this cursor.</ResponseField>
<ResponseField name="before" type="Optional[str]">A cursor for use in pagination, fetching records before this cursor.</ResponseField>

* `filters` *Optional\[generations\_filters]* - Filters to apply to the generations query.
* `order_by` *Optional\[generations\_order\_by]* - Ordering options for the generations.

**Returns**:

The result of the GraphQL helper function for fetching generations.

<a id="literalai.api.__init__.AsyncLiteralAPI.create_generation" />

#### create\_generation

```python theme={null}
async def create_generation(generation: Union[ChatGeneration,
                                              CompletionGeneration])
```

Asynchronously creates a new generation with the specified details.

**Arguments**:

<ResponseField name="generation" type="Union[ChatGeneration, CompletionGeneration]">The generation data to create.</ResponseField>

**Returns**:

The result of the GraphQL helper function for creating a generation.

<a id="literalai.api.__init__.AsyncLiteralAPI.create_dataset" />

#### create\_dataset

```python theme={null}
async def create_dataset(name: str,
                         description: Optional[str] = None,
                         metadata: Optional[Dict] = None,
                         type: DatasetType = "key_value")
```

Asynchronously creates a new dataset with the specified details.

**Arguments**:

<ResponseField name="name" type="str">The name of the dataset.</ResponseField>
<ResponseField name="description" type="Optional[str]">A description of the dataset.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Metadata associated with the dataset.</ResponseField>
<ResponseField name="type" type="DatasetType">The type of the dataset, defaults to "key\_value".</ResponseField>

**Returns**:

The result of the GraphQL helper function for creating a dataset.

<a id="literalai.api.__init__.AsyncLiteralAPI.get_dataset" />

#### get\_dataset

```python theme={null}
async def get_dataset(id: Optional[str] = None, name: Optional[str] = None)
```

Asynchronously retrieves a dataset by its ID or name.

**Arguments**:

<ResponseField name="id" type="Optional[str]">The unique identifier of the dataset to retrieve.</ResponseField>
<ResponseField name="name" type="Optional[str]">The name of the dataset to retrieve.</ResponseField>

**Returns**:

The processed response from the REST API call.

<a id="literalai.api.__init__.AsyncLiteralAPI.update_dataset" />

#### update\_dataset

```python theme={null}
async def update_dataset(id: str,
                         name: Optional[str] = None,
                         description: Optional[str] = None,
                         metadata: Optional[Dict] = None)
```

Asynchronously updates an existing dataset identified by its ID with new details.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the dataset to update.</ResponseField>
<ResponseField name="name" type="Optional[str]">The new name of the dataset.</ResponseField>
<ResponseField name="description" type="Optional[str]">A new description for the dataset.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">New metadata for the dataset.</ResponseField>

**Returns**:

The result of the GraphQL helper function for updating a dataset.

<a id="literalai.api.__init__.AsyncLiteralAPI.delete_dataset" />

#### delete\_dataset

```python theme={null}
async def delete_dataset(id: str)
```

Asynchronously deletes a dataset identified by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the dataset to delete.</ResponseField>

**Returns**:

The result of the GraphQL helper function for deleting a dataset.

<a id="literalai.api.__init__.AsyncLiteralAPI.create_experiment_item" />

#### create\_experiment\_item

```python theme={null}
async def create_experiment_item(
        experiment_item: DatasetExperimentItem) -> DatasetExperimentItem
```

Asynchronously creates an item within an experiment.

**Arguments**:

<ResponseField name="experiment_item" type="DatasetExperimentItem">The experiment item to be created.</ResponseField>

**Returns**:

<ResponseField name="DatasetExperimentItem">The created experiment item with updated scores.</ResponseField>

<a id="literalai.api.__init__.AsyncLiteralAPI.create_dataset_item" />

#### create\_dataset\_item

```python theme={null}
async def create_dataset_item(dataset_id: str,
                              input: Dict,
                              expected_output: Optional[Dict] = None,
                              metadata: Optional[Dict] = None)
```

Asynchronously creates a dataset item.

**Arguments**:

<ResponseField name="dataset_id" type="str">The unique identifier of the dataset.</ResponseField>
<ResponseField name="input" type="Dict">The input data for the dataset item.</ResponseField>
<ResponseField name="expected_output" type="Optional[Dict]">The expected output data for the dataset item.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Additional metadata for the dataset item.</ResponseField>

**Returns**:

The result of the GraphQL helper function for creating a dataset item.

<a id="literalai.api.__init__.AsyncLiteralAPI.get_dataset_item" />

#### get\_dataset\_item

```python theme={null}
async def get_dataset_item(id: str)
```

Asynchronously retrieves a dataset item by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the dataset item.</ResponseField>

**Returns**:

The result of the GraphQL helper function for fetching a dataset item.

<a id="literalai.api.__init__.AsyncLiteralAPI.delete_dataset_item" />

#### delete\_dataset\_item

```python theme={null}
async def delete_dataset_item(id: str)
```

Asynchronously deletes a dataset item by its ID.

**Arguments**:

<ResponseField name="id" type="str">The unique identifier of the dataset item to delete.</ResponseField>

**Returns**:

The result of the GraphQL helper function for deleting a dataset item.

<a id="literalai.api.__init__.AsyncLiteralAPI.add_step_to_dataset" />

#### add\_step\_to\_dataset

```python theme={null}
async def add_step_to_dataset(dataset_id: str,
                              step_id: str,
                              metadata: Optional[Dict] = None)
```

Asynchronously adds a step to a dataset.

**Arguments**:

<ResponseField name="dataset_id" type="str">The unique identifier of the dataset.</ResponseField>
<ResponseField name="step_id" type="str">The unique identifier of the step to add.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Additional metadata for the step being added.</ResponseField>

**Returns**:

The result of the GraphQL helper function for adding a step to a dataset.

<a id="literalai.api.__init__.AsyncLiteralAPI.add_generation_to_dataset" />

#### add\_generation\_to\_dataset

```python theme={null}
async def add_generation_to_dataset(dataset_id: str,
                                    generation_id: str,
                                    metadata: Optional[Dict] = None)
```

Asynchronously adds a generation to a dataset.

**Arguments**:

<ResponseField name="dataset_id" type="str">The unique identifier of the dataset.</ResponseField>
<ResponseField name="generation_id" type="str">The unique identifier of the generation to add.</ResponseField>
<ResponseField name="metadata" type="Optional[Dict]">Additional metadata for the generation being added.</ResponseField>

**Returns**:

The result of the GraphQL helper function for adding a generation to a dataset.