### Install sference-sdk

Source: https://sference.com/docs/sdk

Installation commands for the sference-sdk package using pip or uv.

```bash
pip install sference-sdk
```

```bash
uv add sference-sdk
```

--------------------------------

### Install Python SDK

Source: https://sference.com/docs/quickstart

Install the Sference Python SDK for application integration.

```bash
pip install sference-sdk
```

--------------------------------

### Verify CLI installation

Source: https://sference.com/docs/cli

Check that the CLI is installed and accessible on your PATH.

```bash
sference --help
```

--------------------------------

### Install sference CLI via package managers

Source: https://sference.com/docs/cli

Alternative installation methods using uv, pip, or pipx.

```bash
uv tool install sference-cli
```

```bash
pip install sference-cli
# or
pipx install sference-cli
```

--------------------------------

### Response Examples

Source: https://sference.com/docs/api-reference/batch-api/V1BatchesBatchIdResultsJsonlGetResultsJsonl

Examples of successful and error response bodies.

```json
"string"
```

```json
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### Create Batch Request Example

Source: https://sference.com/docs/api-reference/batch-api/V1BatchesCreateBatch

Example of a cURL request to create a new batch.

```bash
curl -X POST "https://sference.com/v1/batches" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "body": {
          "property1": null,
          "property2": null
        }
      }
    ]
  }'
```

--------------------------------

### Install sference CLI via shell script

Source: https://sference.com/docs/cli

Use this one-line command to install the CLI on macOS and Linux systems.

```bash
curl -fsSL https://raw.githubusercontent.com/s-ference/sference/main/install.sh | sh
```

--------------------------------

### Custom Model Response Examples

Source: https://sference.com/docs/api-reference

Example responses for successful model creation and bad request errors.

```JSON
{
  "id": "string",
  "display_name": "string",
  "provider": "string",
  "platform_status": "available",
  "modality": "string",
  "context_tokens": 0,
  "released": "string",
  "deprecated": "string",
  "input_per_million_usd": 0,
  "output_per_million_usd": 0,
  "cached_input_per_million_usd": 0,
  "tpm_limit": "unlimited",
  "rpm_limit": "unlimited",
  "requests_per_hour": "—",
  "deployed_on_platform": true,
  "capabilities": {
    "image_input": {
      "supported": false
    },
    "pdf_input": {
      "supported": false
    },
    "thinking": {
      "supported": false,
      "types": {
        "enabled": {
          "supported": false
        },
        "adaptive": {
          "supported": false
        }
      }
    },
    "tools": {
      "supported": false
    },
    "dimensions": 0
  },
  "ownership": "platform",
  "deploy_status": "pending_deploy",
  "architecture": "string",
  "has_hf_token": true,
  "status_reason": "string"
}
```

```JSON
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### API Response Examples

Source: https://sference.com/docs/api-reference/inference-api/V1EmbeddingsCreateEmbedding

Example structures for successful and error responses from the API.

```json
{
  "property1": null,
  "property2": null
}
```

```json
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### Activity Models Response Examples

Source: https://sference.com/docs/api-reference/activity/ControlV1ActivityModelsListModels

Examples of successful and error response bodies returned by the API.

```json
[
  "string"
]
```

```json
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### Response Body Examples

Source: https://sference.com/docs/api-reference/teams/ControlV1TeamsMeUpdateMe

Examples of successful 200 OK and error 400 Bad Request response payloads.

```json
{
  "id": "string",
  "name": "string",
  "email_domain": "string",
  "role": "string",
  "zero_data_retention_enabled": false,
  "members": [
    {
      "user_id": "string",
      "email": "string",
      "role": "string",
      "is_active": true,
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}
```

```json
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### Create Deployment cURL Request

Source: https://sference.com/docs/api-reference/deployments/ControlV1DeploymentsCreateDeployment

Example of how to initiate a deployment using a cURL command.

```bash
curl -X POST "https://sference.com/control/v1/deployments" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "model_source": "platform",
    "model_id": "string"
  }'
```

--------------------------------

### Deployment Response Examples

Source: https://sference.com/docs/api-reference/deployments/ControlV1DeploymentsCreateDeployment

JSON structures for successful deployment creation and error responses.

```json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "model_source": "platform",
  "model_id": "string",
  "region": "string",
  "performance": "cost_saving",
  "min_replicas": 0,
  "max_replicas": 0,
  "notes": "string",
  "status": "pending_deploy",
  "status_reason": "string",
  "activated_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
```

```json
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### Initialize Sference SDK Environment

Source: https://sference.com/docs/sdk

Commands to clone the repository, install dependencies, and configure the API key and model ID.

```bash
git clone https://github.com/s-ference/sference.git
cd sference
uv sync --group dev --group examples
export SFERENCE_API_KEY='sk_...'
export SFERENCE_MODEL='Qwen/Qwen3.6-35B-A3B'   # model id from your deployment
```

--------------------------------

### Initialize sference CLI and run inference

Source: https://sference.com/docs

Install the CLI, authenticate with an API key, and execute a synchronous inference request.

```bash
curl -fsSL https://raw.githubusercontent.com/s-ference/sference/main/install.sh | sh
export SFERENCE_API_KEY="sk_..."
sference auth login --api-key "$SFERENCE_API_KEY"
sference responses create --model "Qwen/Qwen3.6-35B-A3B" --content "Say hello in one sentence." --wait
```

--------------------------------

### JSONL Response

Source: https://sference.com/docs/api-reference/batch-api

Example response for JSONL results.

```json
"string"
```

--------------------------------

### GET /v1/models

Source: https://sference.com/docs/api-reference/inference-api/V1ModelsListModels

Retrieves a list of all available models.

```APIDOC
## GET /v1/models

### Description
Retrieves a list of available models supported by the Sference platform.

### Method
GET

### Endpoint
https://sference.com/v1/models

### Response
#### Success Response (200)
- **object** (string) - The type of the object, which is 'list'.
- **data** (array) - A list of model objects.

#### Response Example
{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "model",
      "created": 0,
      "owned_by": "sference",
      "display_name": "string",
      "modality": "text_generation",
      "capabilities": {
        "image_input": { "supported": false },
        "pdf_input": { "supported": false },
        "thinking": {
          "supported": false,
          "types": {
            "enabled": { "supported": false },
            "adaptive": { "supported": false }
          }
        },
        "tools": { "supported": false },
        "dimensions": 0
      },
      "context_tokens": 0,
      "provider": "string",
      "pricing": {
        "input_per_million_usd": 0,
        "output_per_million_usd": 0,
        "cached_input_per_million_usd": 0
      },
      "released": "string"
    }
  ]
}
```

--------------------------------

### Run Prefect Batch Workflow

Source: https://sference.com/docs/sdk

Commands to execute the Prefect batch response example locally or deploy it as a service.

```bash
uv run python examples/prefect/ai_data_analyst_batch_responses.py
```

```bash
uv run python examples/prefect/ai_data_analyst_batch_responses.py --serve
```

--------------------------------

### Batch JSONL input format

Source: https://sference.com/docs/cli

Example of a JSONL file structure for batch inference requests.

```json
{"custom_id":"a","method":"POST","url":"/v1/chat/completions","body":{"model":"…","messages":[{"role":"user","content":"hi"}]}}
{"custom_id":"b","method":"POST","url":"/v1/responses","body":{"model":"…","input":[{"role":"user","content":"hi"}]}}
{"content":"content-only — pass --model on submit"}
```

--------------------------------

### GET /control/v1/billing/summary

Source: https://sference.com/docs/api-reference/billing

Retrieves a summary of usage and costs for the account.

```APIDOC
## GET /control/v1/billing/summary

### Description
Retrieves a summary of usage and costs for the account.

### Method
GET

### Endpoint
https://sference.com/control/v1/billing/summary

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Number of days to summarize (1-365, default 30).

### Response
#### Success Response (200)
- **summary** (object) - Usage summary metrics.
- **by_model** (array) - Breakdown of usage by model.
```

--------------------------------

### Create Chat Completion with cURL

Source: https://sference.com/docs/api-reference/inference-api/V1ChatCompletionsCreateChatCompletion

Example request to the chat completions endpoint using cURL.

```bash
curl -X POST "https://sference.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "string",
    "messages": [
      {
        "role": "string"
      }
    ]
  }'
```

--------------------------------

### GET /control/v1/deployments

Source: https://sference.com/docs/api-reference/deployments/ControlV1DeploymentsListDeployments

Retrieves a list of all deployments associated with the account.

```APIDOC
## GET /control/v1/deployments

### Description
Retrieves a list of all deployments.

### Method
GET

### Endpoint
https://sference.com/control/v1/deployments

### Response
#### Success Response (200)
- **items** (array) - A list of deployment objects.

#### Response Example
{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "model_source": "platform",
      "model_id": "string",
      "region": "string",
      "performance": "cost_saving",
      "min_replicas": 0,
      "max_replicas": 0,
      "notes": "string",
      "status": "pending_deploy",
      "status_reason": "string",
      "activated_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}
```

--------------------------------

### GET /control/v1/activity/models

Source: https://sference.com/docs/api-reference/activity

Retrieves a list of models used in activities.

```APIDOC
## GET /control/v1/activity/models

### Description
Retrieves a list of models used in activities.

### Method
GET

### Endpoint
/control/v1/activity/models

### Parameters
#### Query Parameters
- **user_id** (string) - Optional - Team admins: filter models to one member

### Response
#### Success Response (200)
- **models** (array) - List of model names

#### Response Example
[
  "string"
]
```

--------------------------------

### Add Member Response Schemas

Source: https://sference.com/docs/api-reference/teams/ControlV1TeamsMeMembersAddMember

Example JSON structures for successful member creation and error responses.

```json
{
  "user_id": "string",
  "email": "string",
  "role": "string",
  "is_active": true,
  "created_at": "2019-08-24T14:15:22Z"
}
```

```json
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### GET /v1/responses

Source: https://sference.com/docs/api-reference

Retrieves a list of responses.

```APIDOC
## GET /v1/responses

### Description
Retrieves a list of responses.

### Method
GET

### Endpoint
/v1/responses

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of items to return (Default: 100)
- **stream_id** (string|null) - Optional - Filter by stream ID

### Response
#### Success Response (200)
- **object** (string) - Object type
- **data** (array) - List of response objects
- **has_more** (boolean) - Whether more items are available

#### Response Example
{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "response",
      "created_at": 0,
      "model": "string",
      "status": "in_progress"
    }
  ],
  "has_more": false
}
```

--------------------------------

### Create Custom Model Request

Source: https://sference.com/docs/api-reference/model-catalog/ControlV1ModelsCustomCreateCustomModel

Example cURL request to register a new custom model.

```bash
curl -X POST "https://sference.com/control/v1/models/custom" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "string",
    "architecture": "qwen"
  }'
```

--------------------------------

### Search Models Response Schemas

Source: https://sference.com/docs/api-reference/model-catalog/ControlV1ModelsSearchSearchModels

Example JSON structures for successful and error responses.

```json
{
  "items": [
    {
      "id": "string",
      "display_name": "string",
      "provider": "string",
      "modality": "text_generation",
      "context_tokens": 0,
      "released": "string",
      "input_per_million_usd": 0,
      "output_per_million_usd": 0,
      "cached_input_per_million_usd": 0,
      "tpm_limit": "unlimited",
      "rpm_limit": "unlimited",
      "requests_per_hour": "—",
      "catalog_status": "available",
      "deployed_on_platform": true,
      "source": "catalog"
    }
  ]
}
```

```json
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### Activity Response Schemas

Source: https://sference.com/docs/api-reference/activity/ControlV1ActivityRequestIdGetActivityDetail

Example JSON structures for successful activity retrieval and error responses.

```json
{
  "id": "string",
  "status": "pending",
  "model": "string",
  "custom_id": "string",
  "type": "standalone",
  "batch_id": "string",
  "stream_id": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "prompt_tokens": 0,
  "completion_tokens": 0,
  "total_tokens": 0,
  "cached_prompt_tokens": 0,
  "cost_micros": 0,
  "body_json": {},
  "result_json": {},
  "error_json": {}
}
```

```json
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### GET /v1/batches

Source: https://sference.com/docs/api-reference/batch-api/V1BatchesListBatches

Retrieves a list of batches from the Sference API.

```APIDOC
## GET /v1/batches

### Description
Retrieves a list of all batches associated with the account.

### Method
GET

### Endpoint
https://sference.com/v1/batches

### Response
#### Success Response (200)
- **items** (array) - A list of batch objects.
  - **id** (string) - The unique identifier of the batch.
  - **status** (string) - The current status of the batch (e.g., pending).
  - **window** (string) - The time window for the batch.
  - **request_count** (integer) - The number of requests in the batch.
  - **created_at** (string) - Timestamp of creation.
  - **updated_at** (string) - Timestamp of last update.
  - **completed_at** (string) - Timestamp of completion.
  - **total_prompt_tokens** (integer) - Total prompt tokens used.
  - **total_completion_tokens** (integer) - Total completion tokens used.
  - **total_tokens** (integer) - Total tokens used.
  - **total_cost_micros** (integer) - Total cost in micros.

#### Response Example
{
  "items": [
    {
      "id": "string",
      "status": "pending",
      "window": "24h",
      "request_count": 0,
      "created_at": "string",
      "updated_at": "string",
      "completed_at": "string",
      "total_prompt_tokens": 0,
      "total_completion_tokens": 0,
      "total_tokens": 0,
      "total_cost_micros": 0
    }
  ]
}
```

--------------------------------

### Retrieve Usage Summary via cURL

Source: https://sference.com/docs/api-reference/usage/ControlV1UsageSummaryGetSummary

Executes a GET request to the usage summary endpoint.

```bash
curl -X GET "https://sference.com/control/v1/usage/summary"
```

--------------------------------

### GET /control/v1/models/catalog

Source: https://sference.com/docs/api-reference/model-catalog/ControlV1ModelsCatalogGetCatalog

Retrieves the complete catalog of models available on the platform.

```APIDOC
## GET /control/v1/models/catalog

### Description
Retrieves a list of all models available in the catalog, including details on pricing, capabilities, and current deployment status.

### Method
GET

### Endpoint
https://sference.com/control/v1/models/catalog

### Response
#### Success Response (200)
- **models** (array) - A list of model objects containing metadata, capabilities, and status information.

#### Response Example
{
  "models": [
    {
      "id": "string",
      "display_name": "string",
      "provider": "string",
      "platform_status": "available",
      "modality": "string",
      "context_tokens": 0,
      "released": "string",
      "deprecated": "string",
      "input_per_million_usd": 0,
      "output_per_million_usd": 0,
      "cached_input_per_million_usd": 0,
      "tpm_limit": "unlimited",
      "rpm_limit": "unlimited",
      "requests_per_hour": "—",
      "deployed_on_platform": true,
      "capabilities": {
        "image_input": { "supported": false },
        "pdf_input": { "supported": false },
        "thinking": {
          "supported": false,
          "types": {
            "enabled": { "supported": false },
            "adaptive": { "supported": false }
          }
        },
        "tools": { "supported": false },
        "dimensions": 0
      },
      "ownership": "platform",
      "deploy_status": "pending_deploy",
      "architecture": "string",
      "has_hf_token": true,
      "status_reason": "string"
    }
  ]
}
```

--------------------------------

### GET /v1/batches

Source: https://sference.com/docs/api-reference

Retrieves a list of batch inference jobs.

```APIDOC
## GET /v1/batches

### Description
Retrieves a list of all batch inference jobs.

### Method
GET

### Endpoint
/v1/batches

### Response
#### Success Response (200)
- **items** (array) - List of batch objects.
```

--------------------------------

### Model Catalog Response Schema

Source: https://sference.com/docs/api-reference/model-catalog/ControlV1ModelsCatalogGetCatalog

Example JSON response structure returned by the catalog endpoint.

```json
{
  "models": [
    {
      "id": "string",
      "display_name": "string",
      "provider": "string",
      "platform_status": "available",
      "modality": "string",
      "context_tokens": 0,
      "released": "string",
      "deprecated": "string",
      "input_per_million_usd": 0,
      "output_per_million_usd": 0,
      "cached_input_per_million_usd": 0,
      "tpm_limit": "unlimited",
      "rpm_limit": "unlimited",
      "requests_per_hour": "—",
      "deployed_on_platform": true,
      "capabilities": {
        "image_input": {
          "supported": false
        },
        "pdf_input": {
          "supported": false
        },
        "thinking": {
          "supported": false,
          "types": {
            "enabled": {
              "supported": false
            },
            "adaptive": {
              "supported": false
            }
          }
        },
        "tools": {
          "supported": false
        },
        "dimensions": 0
      },
      "ownership": "platform",
      "deploy_status": "pending_deploy",
      "architecture": "string",
      "has_hf_token": true,
      "status_reason": "string"
    }
  ]
}
```

--------------------------------

### Retrieve Billing Summary via cURL

Source: https://sference.com/docs/api-reference/billing/ControlV1BillingSummaryGetSummary

Executes a GET request to the billing summary endpoint.

```bash
curl -X GET "https://sference.com/control/v1/billing/summary"
```

--------------------------------

### Daily Usage Response Schemas

Source: https://sference.com/docs/api-reference/usage

Example JSON structures for successful and error responses from the daily usage endpoint.

```JSON
{
  "items": [
    {
      "date": "string",
      "model": "string",
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 0,
      "cached_prompt_tokens": 0,
      "request_count": 0,
      "cost_micros": 0
    }
  ]
}
```

```JSON
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### Batch Response Schemas

Source: https://sference.com/docs/api-reference/batch-api/V1BatchesBatchIdGetBatch

Example JSON structures for successful 200 OK responses and 400 Bad Request error responses.

```json
{
  "id": "string",
  "status": "pending",
  "window": "24h",
  "request_count": 0,
  "created_at": "string",
  "updated_at": "string",
  "completed_at": "string",
  "total_prompt_tokens": 0,
  "total_completion_tokens": 0,
  "total_tokens": 0,
  "total_cost_micros": 0
}
```

```json
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### JSONL Batch Input Formats

Source: https://sference.com/docs/guides/batches

Examples of JSONL input formats for batch processing, including OpenAI-style envelopes and content-only rows.

```json
{"custom_id":"a","method":"POST","url":"/v1/chat/completions","body":{"model":"…","messages":[{"role":"user","content":"hi"}]}}
{"custom_id":"b","method":"POST","url":"/v1/responses","body":{"model":"…","input":[{"role":"user","content":"hi"}]}}
```

```json
{"content":"Classify this log line."}
```

--------------------------------

### List Activities cURL Request

Source: https://sference.com/docs/api-reference/activity/ControlV1ActivityListActivity

Retrieve a list of activities using a standard GET request.

```bash
curl -X GET "https://sference.com/control/v1/activity"
```

--------------------------------

### GET /control/v1/usage/summary

Source: https://sference.com/docs/api-reference/usage

Retrieves an aggregated summary of usage statistics, broken down by model and total metrics.

```APIDOC
## GET /control/v1/usage/summary

### Description
Retrieves an aggregated summary of usage statistics, broken down by model and total metrics.

### Method
GET

### Endpoint
https://sference.com/control/v1/usage/summary

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Number of days to look back (Default: 30, Range: 1-365)
- **user_id** (string|null) - Optional - Team admins: filter usage to one member

### Response
#### Success Response (200)
- **summary** (object) - Total usage metrics
- **by_model** (array) - Usage metrics broken down by model

#### Response Example
{
  "summary": {
    "total_prompt_tokens": 0,
    "total_completion_tokens": 0,
    "total_tokens": 0,
    "total_cached_prompt_tokens": 0,
    "total_requests": 0,
    "total_cost_micros": 0
  },
  "by_model": [
    {
      "model": "string",
      "service_tier": "default",
      "total_prompt_tokens": 0,
      "total_completion_tokens": 0,
      "total_tokens": 0,
      "total_cached_prompt_tokens": 0,
      "total_requests": 0,
      "total_cost_micros": 0
    }
  ]
}
```

--------------------------------

### Retrieve Daily Usage via cURL

Source: https://sference.com/docs/api-reference/usage/ControlV1UsageDailyGetDaily

Executes a GET request to the daily usage endpoint.

```bash
curl -X GET "https://sference.com/control/v1/usage/daily"
```

--------------------------------

### List Models Request

Source: https://sference.com/docs/api-reference/inference-api/V1ModelsListModels

Retrieves the list of available models using a standard GET request.

```cURL
curl -X GET "https://sference.com/v1/models"
```

--------------------------------

### GET /control/v1/usage/summary

Source: https://sference.com/docs/api-reference/usage/ControlV1UsageSummaryGetSummary

Retrieves a summary of usage metrics including token counts and costs, with optional filtering by days and user ID.

```APIDOC
## GET /control/v1/usage/summary

### Description
Retrieves a summary of usage metrics including token counts and costs, with optional filtering by days and user ID.

### Method
GET

### Endpoint
https://sference.com/control/v1/usage/summary

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Number of days to look back (Default: 30, Range: 1-365)
- **user_id** (string|null) - Optional - Team admins: filter usage to one member

### Response
#### Success Response (200)
- **summary** (object) - Aggregated usage statistics
- **by_model** (array) - Usage statistics broken down by model

#### Response Example
{
  "summary": {
    "total_prompt_tokens": 0,
    "total_completion_tokens": 0,
    "total_tokens": 0,
    "total_cached_prompt_tokens": 0,
    "total_requests": 0,
    "total_cost_micros": 0
  },
  "by_model": [
    {
      "model": "string",
      "service_tier": "default",
      "total_prompt_tokens": 0,
      "total_completion_tokens": 0,
      "total_tokens": 0,
      "total_cached_prompt_tokens": 0,
      "total_requests": 0,
      "total_cost_micros": 0
    }
  ]
}

#### Error Response (400)
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### GET /control/v1/usage/daily

Source: https://sference.com/docs/api-reference/usage

Retrieves daily usage statistics, including token counts and costs, for a specified number of days.

```APIDOC
## GET /control/v1/usage/daily

### Description
Retrieves daily usage statistics, including token counts and costs, for a specified number of days.

### Method
GET

### Endpoint
https://sference.com/control/v1/usage/daily

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Number of days to look back (Default: 30, Range: 1-365)
- **user_id** (string|null) - Optional - Team admins: filter usage to one member

### Response
#### Success Response (200)
- **items** (array) - List of daily usage records

#### Response Example
{
  "items": [
    {
      "date": "string",
      "model": "string",
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 0,
      "cached_prompt_tokens": 0,
      "request_count": 0,
      "cost_micros": 0
    }
  ]
}
```

--------------------------------

### Batch Results Response Schemas

Source: https://sference.com/docs/api-reference/batch-api/V1BatchesBatchIdResultsGetResults

Example JSON structures for successful (200) and error (400) responses.

```json
{
  "batch_id": "string",
  "status": "pending",
  "output_url": "string",
  "completed_at": "string",
  "results": [
    {
      "property1": null,
      "property2": null
    }
  ]
}
```

```json
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### GET /control/v1/activity

Source: https://sference.com/docs/api-reference/activity/ControlV1ActivityListActivity

Retrieves a paginated list of activities, with optional filtering by type, status, model, creation date, API key, or user ID.

```APIDOC
## GET /control/v1/activity

### Description
Retrieves a list of activities. Supports pagination and various filtering options.

### Method
GET

### Endpoint
https://sference.com/control/v1/activity

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Default: 1. Range: >= 1.
- **page_size** (integer) - Optional - Default: 25. Range: 1 to 100.
- **type** (string) - Optional - Filter by activity type.
- **status** (string) - Optional - Filter by activity status.
- **model** (string) - Optional - Filter by model.
- **created_after** (string) - Optional - Filter by creation date.
- **created_before** (string) - Optional - Filter by creation date.
- **api_key_id** (string) - Optional - Filter activity to one API key.
- **user_id** (string) - Optional - Team admins: filter activity to one member.

### Response
#### Success Response (200)
- **items** (array) - List of activity objects.
- **page** (integer) - Current page number.
- **page_size** (integer) - Number of items per page.
- **total** (integer) - Total number of activities.

#### Error Response (400)
- **status_code** (integer) - 400
- **detail** (string) - Error description
- **extra** (object) - Additional error details
```

--------------------------------

### List Activity Models cURL Request

Source: https://sference.com/docs/api-reference/activity/ControlV1ActivityModelsListModels

Use this cURL command to perform a GET request to the activity models endpoint.

```bash
curl -X GET "https://sference.com/control/v1/activity/models"
```

--------------------------------

### POST /control/v1/deployments

Source: https://sference.com/docs/api-reference/deployments/ControlV1DeploymentsCreateDeployment

Creates a new deployment instance in the Sference environment.

```APIDOC
## POST /control/v1/deployments

### Description
Creates a new deployment with the specified configuration.

### Method
POST

### Endpoint
https://sference.com/control/v1/deployments

### Parameters
#### Request Body
- **name** (string) - Required - 1 <= length <= 256
- **model_source** (string) - Required - "platform" | "custom"
- **model_id** (string) - Required - 1 <= length <= 512
- **region** (string) - Optional - Default: "emea", "emea" | "global"
- **performance** (string) - Optional - Default: "standard", "cost_saving" | "standard" | "turbo"
- **min_replicas** (integer) - Optional - Default: 0, 0 <= value <= 1000
- **max_replicas** (integer) - Optional - Default: 1, 0 <= value <= 1000
- **notes** (string) - Optional - length <= 4000

### Request Example
{
  "name": "string",
  "model_source": "platform",
  "model_id": "string"
}

### Response
#### Success Response (201)
- **id** (string) - Deployment ID
- **name** (string) - Deployment name
- **model_source** (string) - Source of the model
- **model_id** (string) - ID of the model
- **region** (string) - Deployment region
- **performance** (string) - Performance tier
- **min_replicas** (integer) - Minimum replicas
- **max_replicas** (integer) - Maximum replicas
- **notes** (string) - Deployment notes
- **status** (string) - Current status
- **status_reason** (string) - Reason for status
- **activated_at** (string) - Activation timestamp
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Last update timestamp

#### Response Example
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "model_source": "platform",
  "model_id": "string",
  "region": "string",
  "performance": "cost_saving",
  "min_replicas": 0,
  "max_replicas": 0,
  "notes": "string",
  "status": "pending_deploy",
  "status_reason": "string",
  "activated_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
```

--------------------------------

### Authenticate with sference API

Source: https://sference.com/docs/cli

Set the API key environment variable and log in to the CLI.

```bash
export SFERENCE_API_KEY='sk_...'
sference auth login --api-key "$SFERENCE_API_KEY"
sference auth me --json
```

--------------------------------

### Get Current Team via cURL

Source: https://sference.com/docs/api-reference/teams/ControlV1TeamsMeGetMe

Use this command to fetch team details using the GET method.

```bash
curl -X GET "https://sference.com/control/v1/teams/me"
```

--------------------------------

### Submit and process a batch with Python SDK

Source: https://sference.com/docs/guides/batches

Initializes the Sference client to submit a batch job, wait for its completion, and download the resulting JSONL file.

```python
from sference_sdk import SferenceClient

client = SferenceClient(api_key="sk_...")
batch = client.submit_batch(
    input_file="./workload.jsonl",
    model="Qwen/Qwen3.6-35B-A3B",
    window="24h",
)
done = client.wait_for_completion(batch.id, poll_interval=5.0, timeout=86_400.0)
client.download_results_jsonl(done.id, out="./results.jsonl")
```

--------------------------------

### GET /v1/responses

Source: https://sference.com/docs/api-reference/inference-api/V1ResponsesListResponses

Retrieves a list of inference responses.

```APIDOC
## GET /v1/responses

### Description
Retrieves a list of inference responses.

### Method
GET

### Endpoint
https://sference.com/v1/responses

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Default: 100
- **stream_id** (string|null) - Optional - Filter by stream ID

### Response
#### Success Response (200)
- **object** (string) - The type of object returned
- **data** (array) - List of response objects
- **has_more** (boolean) - Indicates if there are more pages available

#### Response Example
{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "response",
      "created_at": 0,
      "model": "string",
      "status": "in_progress"
    }
  ],
  "has_more": false
}
```

--------------------------------

### Configure API Credentials

Source: https://sference.com/docs/sdk

Set the SFERENCE_API_KEY environment variable for authentication.

```bash
export SFERENCE_API_KEY='sk_...'
```

--------------------------------

### Skill File Path

Source: https://sference.com/docs/sdk

Recommended file path for the Sference skill file within a Cursor project.

```text
.cursor/skills/sference-sdk/SKILL.md
```

--------------------------------

### GET /control/v1/deployments

Source: https://sference.com/docs/api-reference/deployments

Retrieves a list of all active model deployments.

```APIDOC
## GET /control/v1/deployments

### Description
Retrieves a list of all model deployments associated with the account.

### Method
GET

### Endpoint
https://sference.com/control/v1/deployments

### Response
#### Success Response (200)
- **items** (array) - List of deployment objects

#### Response Example
{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "model_source": "platform",
      "model_id": "string",
      "region": "string",
      "performance": "cost_saving",
      "min_replicas": 0,
      "max_replicas": 0,
      "notes": "string",
      "status": "pending_deploy",
      "status_reason": "string",
      "activated_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}
```

--------------------------------

### Create Deployment POST Request

Source: https://sference.com/docs/api-reference/deployments

Creates a new deployment using the specified configuration.

```cURL
curl -X POST "https://sference.com/control/v1/deployments" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "model_source": "platform",    "model_id": "string"  }'
```

--------------------------------

### Run Inference Request

Source: https://sference.com/docs/quickstart

Create a response and wait for completion using the CLI.

```bash
sference responses create \
  --model "Qwen/Qwen3.6-35B-A3B" \
  --content "Write a one-sentence greeting for an inference platform." \
  --wait
```

--------------------------------

### GET /control/v1/billing/transactions

Source: https://sference.com/docs/api-reference/billing/ControlV1BillingTransactionsGetTransactions

Retrieves a list of billing transactions for the account.

```APIDOC
## GET /control/v1/billing/transactions

### Description
Retrieves a paginated list of billing transactions.

### Method
GET

### Endpoint
https://sference.com/control/v1/billing/transactions

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Default: 25, Range: 1-100
- **starting_after** (string|null) - Optional - Cursor for pagination

### Response
#### Success Response (200)
- **items** (array) - List of transaction objects
- **next_starting_after** (string) - Cursor for the next page

#### Response Example
{
  "items": [
    {
      "id": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "type": "string",
      "amount_micros": 0,
      "balance_after_micros": 0,
      "description": "string",
      "external_provider": "string",
      "external_payment_id": "string"
    }
  ],
  "next_starting_after": "string"
}

#### Error Response (400)
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```

--------------------------------

### Create Topup cURL Request

Source: https://sference.com/docs/api-reference/billing/ControlV1BillingTopupsCreateTopup

Use this cURL command to initiate a topup request to the billing service.

```bash
curl -X POST "https://sference.com/control/v1/billing/topups?nonce=string" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": "string"
  }'
```

--------------------------------

### GET /v1/responses/events

Source: https://sference.com/docs/api-reference/inference-api/V1ResponsesEventsListResponseEvents

Retrieves a list of response events from the inference service.

```APIDOC
## GET /v1/responses/events

### Description
Retrieves a list of response events. Supports filtering by stream ID and pagination using cursor-based parameters.

### Method
GET

### Endpoint
https://sference.com/v1/responses/events

### Parameters
#### Query Parameters
- **stream_id** (string|null) - Optional - Filter events by stream ID.
- **limit** (integer) - Optional - Number of items to return (Default: 20).
- **starting_after** (string|null) - Optional - Cursor for pagination.
- **ending_before** (string|null) - Optional - Cursor for pagination.
- **wait_ms** (integer) - Optional - Wait time in milliseconds (Default: 0).

### Request Example
curl -X GET "https://sference.com/v1/responses/events"

### Response
#### Success Response (200)
- **object** (string) - The type of object returned (list).
- **data** (array) - List of response event objects.
- **has_more** (boolean) - Indicates if there are more pages available.

#### Response Example
{
  "object": "list",
  "data": [
    {
      "completion_id": "string",
      "response_id": "string",
      "custom_id": "string",
      "status": "string",
      "result": {
        "property1": null,
        "property2": null
      },
      "error": {
        "property1": null,
        "property2": null
      },
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 0,
      "cost_micros": 0,
      "completed_at": "string"
    }
  ],
  "has_more": true
}
```

--------------------------------

### GET /v1/auth/me

Source: https://sference.com/docs/api-reference/inference-api/V1AuthMeMe

Retrieves the profile information for the currently authenticated user.

```APIDOC
## GET /v1/auth/me

### Description
Retrieves the username and role of the currently authenticated user.

### Method
GET

### Endpoint
https://sference.com/v1/auth/me

### Response
#### Success Response (200)
- **username** (string) - The username of the authenticated user.
- **role** (string) - The role assigned to the user.

#### Response Example
{
  "username": "string",
  "role": "string"
}
```

--------------------------------

### Get Batch Details

Source: https://sference.com/docs/api-reference/batch-api

Retrieves details for a specific batch by ID.

```curl
curl -X GET "https://example.com/v1/batches/497f6eca-6276-4993-bfeb-53cbbbba6f08"
```

--------------------------------

### GET /control/v1/billing/summary

Source: https://sference.com/docs/api-reference/billing/ControlV1BillingSummaryGetSummary

Retrieves the billing summary for a specified number of days.

```APIDOC
## GET /control/v1/billing/summary

### Description
Retrieves a summary of billing and usage metrics, including token consumption and estimated costs.

### Method
GET

### Endpoint
https://sference.com/control/v1/billing/summary

### Parameters
#### Query Parameters
- **days** (integer) - Optional - The number of days to include in the summary. Default is 30. Range: 1 to 365.

### Response
#### Success Response (200)
- **summary** (object) - Aggregated usage data including tokens, requests, and costs.
- **by_model** (array) - Detailed usage breakdown per model.

#### Response Example
{
  "summary": {
    "days": 0,
    "total_prompt_tokens": 0,
    "total_completion_tokens": 0,
    "total_tokens": 0,
    "total_cached_prompt_tokens": 0,
    "total_requests": 0,
    "estimated_cost_micros": 0,
    "credit_balance_micros": 0
  },
  "by_model": [
    {
      "model": "string",
      "service_tier": "default",
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 0,
      "cached_prompt_tokens": 0,
      "total_requests": 0,
      "cost_micros": 0,
      "pricing": {
        "model": "string",
        "prompt_token_price_micros": 0,
        "completion_token_price_micros": 0,
        "effective_from": "2019-08-24T14:15:22Z"
      }
    }
  ]
}
```

--------------------------------

### Create Top-up Request

Source: https://sference.com/docs/api-reference/billing

Sends a POST request to initiate a top-up with a required nonce for idempotency.

```cURL
curl -X POST "https://sference.com/control/v1/billing/topups?nonce=string" \  -H "Content-Type: application/json" \  -d '{    "amount_usd": "string"  }'
```

--------------------------------

### GET /v1/batches/{batch_id}

Source: https://sference.com/docs/api-reference/batch-api/V1BatchesBatchIdGetBatch

Retrieves the details of a specific batch by its UUID.

```APIDOC
## GET /v1/batches/{batch_id}

### Description
Retrieves the status and metadata for a specific batch identified by its UUID.

### Method
GET

### Endpoint
https://sference.com/v1/batches/{batch_id}

### Parameters
#### Path Parameters
- **batch_id** (string) - Required - The unique identifier of the batch (UUID format).

### Request Example
```bash
curl -X GET "https://sference.com/v1/batches/497f6eca-6276-4993-bfeb-53cbbbba6f08"
```

### Response
#### Success Response (200)
- **id** (string) - Batch identifier
- **status** (string) - Current status (e.g., pending)
- **window** (string) - Time window
- **request_count** (integer) - Number of requests
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Last update timestamp
- **completed_at** (string) - Completion timestamp
- **total_prompt_tokens** (integer) - Total prompt tokens used
- **total_completion_tokens** (integer) - Total completion tokens used
- **total_tokens** (integer) - Total tokens used
- **total_cost_micros** (integer) - Total cost in micros

#### Error Response (400)
- **status_code** (integer) - 400
- **detail** (string) - Error description
- **extra** (object) - Additional error details
```

--------------------------------

### Request Model Deployment via cURL

Source: https://sference.com/docs/api-reference/model-catalog/ControlV1ModelsRequestDeploymentRequestModelDeployment

Initiate a model deployment request using a POST request with a JSON body.

```bash
curl -X POST "https://sference.com/control/v1/models/request-deployment" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "string"
  }'
```