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

# Engagements

An engagement represents a service or activity performed for one of your clients. When you create an engagement within an organization, it will always be associated with that organization. Engagements house the analyses you run within MindBridge, like the general ledger analysis.

Because engagements belong to an organization, see [Organizations](/sdk/python/tutorials/organizations) for how to work with organizations using the Python SDK.

## Create a new engagement

As in the web application, you can [create an engagement](https://support.mindbridge.ai/hc/en-us/articles/360055739694-Create-an-engagement) using the Python SDK.

<CodeGroup dropdown>
  ```python theme={null}
  organization = server.organizations.get_by_id("6793acbf7bd84f04412b114e")  # (1)!

  engagement = mbapi.EngagementItem(  # (2)!
      name="The Engagement Name",
      organization_id=organization.id,
      engagement_lead_id=organization.created_user_info.id,
  )
  engagement = server.engagements.create(engagement)
  print(f"{engagement.id=}\n{engagement.name=}")
  #> engagement.id='695fcdfa1bcebb393be82967'
  #> engagement.name='The Engagement Name'
  ```
</CodeGroup>

1. See [Organizations](/sdk/python/tutorials/organizations) for how to create the `server` and create an organization.
2. It is assumed you have imported the module with `import mindbridgeapi as mbapi`.

## Retrieving an engagement by ID

You can retrieve an existing engagement by `id`. The example below uses the `id` of the engagement you created above.

<CodeGroup dropdown>
  ```python theme={null}
  engagement = server.engagements.get_by_id("695fcdfa1bcebb393be82967")
  print(f"{engagement.id=}\n{engagement.name=}")
  #> engagement.id='695fcdfa1bcebb393be82967'
  #> engagement.name='The Engagement Name'
  ```
</CodeGroup>

## Querying engagements

Query engagements, optionally applying a filter. Engagements can be searched using the MindBridge Query Language, as described in the MindBridge API Reference. The `get` function returns a [generator](https://docs.python.org/3/reference/expressions.html#generator-expressions), allowing you to iterate over search results or use the [`next()`](https://docs.python.org/3/library/functions.html#next) function.

To list engagements for an existing organization, use the `engagements` property of the organization, which yields a generator of engagements within that organization.

<CodeGroup dropdown>
  ```python theme={null}
  organization = server.organizations.get_by_id("6793acbf7bd84f04412b114e")

  try:
      engagement = next(organization.engagements)
      print(f"{engagement.id=}\n{engagement.name=}")
  except StopIteration:
      print("This organization has no engagements.")

  #> engagement.id='695fcdfa1bcebb393be82967'
  #> engagement.name='The Engagement Name'
  ```
</CodeGroup>