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

# List world lifecycle events

> World and twin lifecycle events, newest first: created, twin linked, seed stored, status changed, reset, stopped.

Use the [SDK setup](/api-reference/languages/overview#use-the-guide-examples) with CHRONICLE_API_KEY and CHRONICLE_API_URL. The Go and Rust samples are complete entry points; Rust also needs Tokio (see [Rust setup](/api-reference/languages/rust)). Set WORLD_ID to the world.id returned by a launch or world-list result.

The schema below is the HTTP representation. SDKs normalize field names and list wrappers; see [SDK and HTTP fields](/api-reference/worldsmith#sdk-and-http-fields).



## OpenAPI

````yaml /api-reference/worldsmith-openapi.json get /v1/worldsmith/worlds/{worldId}/lifecycle
openapi: 3.1.0
info:
  title: Chronicle Labs Worldsmith API
  version: 1.0.0
  description: >-
    Compile blueprints, launch worlds, and read the twins and tasks they create.
    Authenticate every request with your Chronicle API key as a bearer token.
  x-source-contracts: >-
    packages/chronicle/src/json-schema/worldsmith;
    backend/crates/api/src/platform/worldsmith
servers: []
security:
  - ApiKey: []
tags:
  - name: Worldsmith
    description: >-
      Compile blueprints into worlds of connected service twins, launch them,
      and read what they created.
paths:
  /v1/worldsmith/worlds/{worldId}/lifecycle:
    parameters:
      - name: worldId
        in: path
        required: true
        description: The world version ID, from world.id.
        schema:
          type: string
    get:
      tags:
        - Worldsmith
      summary: List world lifecycle events
      description: >-
        World and twin lifecycle events, newest first: created, twin linked,
        seed stored, status changed, reset, stopped.


        Use the [SDK
        setup](/api-reference/languages/overview#use-the-guide-examples) with
        CHRONICLE_API_KEY and CHRONICLE_API_URL. The Go and Rust samples are
        complete entry points; Rust also needs Tokio (see [Rust
        setup](/api-reference/languages/rust)). Set WORLD_ID to the world.id
        returned by a launch or world-list result.


        The schema below is the HTTP representation. SDKs normalize field names
        and list wrappers; see [SDK and HTTP
        fields](/api-reference/worldsmith#sdk-and-http-fields).
      operationId: listWorldLifecycle
      parameters:
        - name: limit
          in: query
          description: Page size, 1 to 100. Default 50.
          schema:
            type: integer
            minimum: 0
            default: 50
        - name: cursor
          in: query
          description: The nextCursor from the previous page. Omit for the newest page.
          schema:
            type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorldLifecycleResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
        - lang: python
          label: Python
          source: |-
            from chronicle import Chronicle
            import os

            world_id = os.environ["WORLD_ID"]
            with Chronicle() as client:
                result = client.worlds.lifecycle.list(world_id, limit=100)
                print(result.items)
                print(result.has_next_page())
        - lang: typescript
          label: TypeScript
          source: >-
            import { Chronicle } from "@chroniclelabs/sdk";


            const client = new Chronicle();

            const worldId = process.env.WORLD_ID;

            if (!worldId) throw new Error("Set WORLD_ID");

            const result = await client.worlds.lifecycle.list(worldId, { limit:
            100 });

            console.log(result.items);

            console.log(result.hasNextPage());
        - lang: javascript
          label: JavaScript
          source: >-
            import { Chronicle } from "@chroniclelabs/sdk";


            const client = new Chronicle();

            const worldId = process.env.WORLD_ID;

            if (!worldId) throw new Error("Set WORLD_ID");

            const result = await client.worlds.lifecycle.list(worldId, { limit:
            100 });

            console.log(result.items);

            console.log(result.hasNextPage());
        - lang: go
          label: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\t\"time\"\n\n\tchronicle \"github.com/chronicle-labs/chronicle-go\"\n)\n\nfunc main() {\n\tif err := example(); err != nil { log.Fatal(err) }\n}\n\nfunc example() error {\n\tctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)\n\tdefer cancel()\n\tclient := chronicle.NewClient()\n\tworldID := os.Getenv(\"WORLD_ID\")\n\tif worldID == \"\" { return fmt.Errorf(\"set WORLD_ID\") }\n\tresult, err := client.Worlds.Lifecycle.List(ctx, worldID, chronicle.PageParams{Limit: 100})\n\tif err != nil {\n\t\treturn err\n\t}\n\tfmt.Println(result.Items)\n\tfmt.Println(result.HasNextPage())\n\treturn nil\n}"
        - lang: rust
          label: Rust
          source: |-
            use chronicle_sdk::Chronicle;
            use chronicle_sdk::types::PageParams;

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                let client = Chronicle::from_env()?;
                let world_id = std::env::var("WORLD_ID")?;
                let result = client.worlds().lifecycle().list(&world_id, PageParams { limit: Some(100), ..Default::default() }).await?;
                println!("{:?}", result.items);
                println!("{}", result.has_next_page());
                Ok(())
            }
components:
  schemas:
    ListWorldLifecycleResponse:
      properties:
        events:
          items:
            $ref: '#/components/schemas/WorldLifecycleEvent'
          type: array
        hasMore:
          type: boolean
        nextCursor:
          type:
            - string
            - 'null'
      required:
        - events
        - hasMore
      type: object
    WorldLifecycleEvent:
      properties:
        entityCount:
          format: int32
          type:
            - integer
            - 'null'
        eventId:
          type: string
        kind:
          $ref: '#/components/schemas/WorldLifecycleKind'
        occurredAt:
          format: date-time
          type: string
        previousStatus:
          anyOf:
            - $ref: '#/components/schemas/TwinInstanceStatus'
            - type: 'null'
        seedSha256:
          type:
            - string
            - 'null'
        service:
          type:
            - string
            - 'null'
        status:
          anyOf:
            - $ref: '#/components/schemas/TwinInstanceStatus'
            - type: 'null'
        twinInstanceId:
          type:
            - string
            - 'null'
      required:
        - eventId
        - kind
        - occurredAt
      type: object
    ApiError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
      example:
        error: World not found
    WorldLifecycleKind:
      enum:
        - world_created
        - twin_linked
        - twin_seed_stored
        - twin_status_changed
        - twin_reset
        - twin_stopped
      type: string
    TwinInstanceStatus:
      type: string
      enum:
        - running
        - provisioning
        - degraded
        - stopped
        - expired
        - failed
      description: >-
        `provisioning`: Row exists; the machine is being created and
        health-gated.


        `degraded`: The machine exists but its last health probe failed.


        `stopped`: Torn down on request.


        `expired`: Torn down by the reaper after its TTL passed.


        `failed`: Provisioning never produced a usable machine.
  responses:
    BadRequest:
      description: Invalid blueprint, cursor, or idempotency key format.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
        text/plain:
          schema:
            type: string
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: No world with this ID in your organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    InternalError:
      description: >-
        Chronicle could not complete the request. Retry, and quote the request
        ID if it persists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Your Chronicle API key (chr_...). Create one in Settings > API keys.

````