Step

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/Step",
  "title": "Step",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "description": "The id of the step. Assigned by the database."
    },
    "origin": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Origin",
      "description": "The surface that this agent step was initiated from."
    },
    "provider_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Provider Id",
      "description": "The unique identifier of the provider that was configured for this step"
    },
    "run_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Run Id",
      "description": "The unique identifier of the run that this step belongs to. Only included for async calls."
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Agent Id",
      "description": "The ID of the agent that performed the step."
    },
    "provider_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Provider Name",
      "description": "The name of the provider used for this step."
    },
    "provider_category": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Provider Category",
      "description": "The category of the provider used for this step."
    },
    "model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Model",
      "description": "The name of the model used for this step."
    },
    "model_handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Model Handle",
      "description": "The model handle (e.g., 'openai/gpt-4o-mini') used for this step."
    },
    "model_endpoint": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Model Endpoint",
      "description": "The model endpoint url used for this step."
    },
    "context_window_limit": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Context Window Limit",
      "description": "The context window limit configured for this step."
    },
    "completion_tokens": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Completion Tokens",
      "description": "The number of tokens generated by the agent during this step."
    },
    "prompt_tokens": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Prompt Tokens",
      "description": "The number of tokens in the prompt during this step."
    },
    "total_tokens": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Total Tokens",
      "description": "The total number of tokens processed by the agent during this step."
    },
    "cached_input_tokens": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cached Input Tokens",
      "description": "The number of input tokens served from cache. None if not reported by provider."
    },
    "cache_write_tokens": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cache Write Tokens",
      "description": "The number of input tokens written to cache (Anthropic only). None if not reported by provider."
    },
    "reasoning_tokens": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Reasoning Tokens",
      "description": "The number of reasoning/thinking tokens generated. None if not reported by provider."
    },
    "completion_tokens_details": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Completion Tokens Details",
      "description": "Detailed completion token breakdown (e.g., reasoning_tokens)."
    },
    "prompt_tokens_details": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Prompt Tokens Details",
      "description": "Detailed prompt token breakdown (e.g., cached_tokens, cache_read_tokens, cache_creation_tokens)."
    },
    "stop_reason": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StopReasonType"
        },
        {
          "type": "null"
        }
      ],
      "description": "The stop reason associated with the step."
    },
    "tags": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Tags",
      "description": "Metadata tags.",
      "default": []
    },
    "tid": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tid",
      "description": "The unique identifier of the transaction that processed this step."
    },
    "trace_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Trace Id",
      "description": "The trace id of the agent step."
    },
    "request_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Request Id",
      "description": "The API request log ID from cloud-api for correlating steps with API requests."
    },
    "messages": {
      "items": {
        "$ref": "#/components/schemas/Message"
      },
      "type": "array",
      "title": "Messages",
      "description": "The messages generated during this step. Deprecated: use `GET /v1/steps/{step_id}/messages` endpoint instead",
      "default": [],
      "deprecated": true
    },
    "feedback": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "positive",
            "negative"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Feedback",
      "description": "The feedback for this step. Must be either 'positive' or 'negative'."
    },
    "project_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Project Id",
      "description": "The project that the agent that executed this step belongs to (cloud only)."
    },
    "error_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Error Type",
      "description": "The type/class of the error that occurred"
    },
    "error_data": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Error Data",
      "description": "Error details including message, traceback, and additional context"
    },
    "status": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StepStatus"
        },
        {
          "type": "null"
        }
      ],
      "description": "Step status: pending, success, or failed",
      "default": "pending"
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "id"
  ]
}