Get impact metrics for a task

POST

impact

curl --request POST \
  --url https://aiapi.scope3.com/v1/impact \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "rows": [
    {
      "utc_datetime": "2022-01-01T00:00:00Z",
      "request_duration_ms": 283,
      "processing_duration_ms": 238,
      "request_cost": 0.18,
      "currency": "USD",
      "integration_source": "litellm",
      "environment": "staging",
      "session_id": "<string>",
      "trace_id": "<string>",
      "request_id": "<string>",
      "client_id": "<string>",
      "project_id": "<string>",
      "application_id": "<string>",
      "model_id": "llama_31_8b",
      "model_family": "llama",
      "model_name": "LLaMa v3.1 8B",
      "model_hugging_face_path": "meta/llama31_8b",
      "model_used_id": "llama_31_8b_0125",
      "base_url": "https://openrouter.ai/api/v1/chat/completions",
      "cloud_region": "us-east-1",
      "managed_service_id": "aws-bedrock",
      "cloud_id": "aws",
      "cloud_instance_id": "p4d.24xlarge",
      "node_id": "aws:p4d.24xlarge",
      "datacenter_id": "550e8400-e29b-41d4-a716-446655440000",
      "country": "US",
      "region": "NY",
      "task": "text-generation",
      "input_tokens": 128,
      "input_audio_seconds": 60,
      "output_tokens": 128,
      "input_images": [
        "1024x1024"
      ],
      "input_steps": 50,
      "output_images": [
        "1024x1024"
      ],
      "output_audio_seconds": 60,
      "output_audio_tokens": 2300,
      "output_video_frames": 60,
      "output_video_resolution": 1080
    }
  ]
}'

{
  "rows": [
    {
      "inference_impact": {
        "usage_energy_wh": 0.13,
        "usage_emissions_gco2e": 0.81,
        "usage_water_ml": 1.32,
        "embodied_emissions_gco2e": 0.81,
        "embodied_water_ml": 1.32
      },
      "training_impact": {
        "usage_energy_wh": 0.13,
        "usage_emissions_gco2e": 0.81,
        "usage_water_ml": 1.32,
        "embodied_emissions_gco2e": 0.81,
        "embodied_water_ml": 1.32
      },
      "fine_tuning_impact": {
        "usage_energy_wh": 0.13,
        "usage_emissions_gco2e": 0.81,
        "usage_water_ml": 1.32,
        "embodied_emissions_gco2e": 0.81,
        "embodied_water_ml": 1.32
      },
      "total_impact": {
        "usage_energy_wh": 0.13,
        "usage_emissions_gco2e": 0.81,
        "usage_water_ml": 1.32,
        "embodied_emissions_gco2e": 0.81,
        "embodied_water_ml": 1.32
      },
      "debug": {
        "model": {
          "id": "gpt-4-turbo",
          "aliases": [
            "claude-latest",
            "claude-3-sonnet-current"
          ],
          "name": "GPT-4 Turbo",
          "family": "gpt",
          "hugging_face_path": "EleutherAI/gpt-neo-2.7B",
          "benchmark_model_id": "GPTJ-6B",
          "total_params_billions": 175,
          "number_of_experts": 7,
          "params_per_expert_billions": 8,
          "tensor_parallelism": 1,
          "datatype": "fp8",
          "task": "text-generation",
          "training_usage_energy_kwh": 1013.1,
          "training_usage_emissions_kgco2e": 1013.1,
          "training_usage_water_l": 1013.1,
          "training_embodied_emissions_kgco2e": 11013.1,
          "training_embodied_water_l": 11013.1,
          "estimated_use_life_days": 1013.1,
          "estimated_requests_per_day": 1013.1,
          "fine_tuned_from_model_id": "llama_31_8b",
          "customer_id": 123,
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "created_by": "<string>"
        },
        "hardware_node": {
          "id": "my-custom-node-1",
          "cloud_id": "aws",
          "cloud_instance_id": "a2-highgpu-1g",
          "managed_service_id": "aws-bedrock",
          "gpu_id": "a100_40gb",
          "gpu_count": 8,
          "cpu_count": 2,
          "idle_power_w_ex_gpu": 100,
          "average_utilization_rate": 0.8,
          "embodied_emissions_kgco2e_ex_gpu": 2500,
          "embodied_water_l_ex_gpu": 2500,
          "use_life_years": 5,
          "customer_id": 123,
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "created_by": "<string>"
        },
        "grid_mix": {
          "country": "US",
          "region": "NY",
          "gco2e_per_kwh": 475
        },
        "steps": [
          {
            "description": "<string>",
            "duration_ms": 123,
            "inferences": 123
          }
        ]
      },
      "error": {
        "code": "<string>",
        "message": "<string>",
        "details": {
          "reason": "<string>",
          "field": "<string>"
        }
      }
    }
  ],
  "total_energy_wh": 0.13,
  "total_gco2e": 0.81,
  "total_mlh2o": 1.32,
  "has_errors": false
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

debug

boolean

Return debug information

Body

application/json

rows

object[]

required

rows.utc_datetime

string

The start time of the request in UTC

Example:

"2022-01-01T00:00:00Z"

rows.request_duration_ms

number

The time the request took (as measured by client or proxy)

Example:

283

rows.processing_duration_ms

number

The time taken in processing the request (as measured at execution)

Example:

238

rows.request_cost

number

The cost to execute this request

Example:

0.18

rows.currency

string

The currency for the cost data

Example:

"USD"

rows.integration_source

string

The integration used to source the data

Example:

"litellm"

rows.environment

string

Environment (prod/production indicates production)

Example:

"staging"

rows.session_id

string

The ID of the session (multiple requests)

rows.trace_id

string

The trace ID of the request (multiple requests in one task)

rows.request_id

string

The unique identifier of this request

rows.client_id

string

The client to attribute this call to

rows.project_id

string

The project to attribute this call to

rows.application_id

string

The application to attribute this call to

rows.model_id

string

The ID of the model requested

Example:

"llama_31_8b"

rows.model_family

string

The family of the model

Example:

"llama"

rows.model_name

string

The name of the model

Example:

"LLaMa v3.1 8B"

rows.model_hugging_face_path

string

The Hugging Face path of the model

Example:

"meta/llama31_8b"

rows.model_used_id

string

The ID of the model that did the inference

Example:

"llama_31_8b_0125"

rows.base_url

string

The URL of the model endpoint

Example:

"https://openrouter.ai/api/v1/chat/completions"

rows.cloud_region

string

Cloud region as defined by the Scope3 API

Required string length: 1 - 64

Example:

"us-east-1"

rows.managed_service_id

string

Managed Service Provider ID

Required string length: 3 - 64

Example:

"aws-bedrock"

rows.cloud_id

string

Cloud ID as defined by the Scope3 API

Required string length: 1 - 64

Example:

"aws"

rows.cloud_instance_id

string

The instance type in the cloud

Example:

"p4d.24xlarge"

rows.node_id

string

The ID of a custom or global node

Example:

"aws:p4d.24xlarge"

rows.datacenter_id

string

The ID of a specific datacenter, either custom or predefined

Example:

"550e8400-e29b-41d4-a716-446655440000"

rows.country

string

Two-letter country code as defined by ISO 3166-1 alpha-2

Required string length: 2

Example:

"US"

rows.region

string

Two-letter region code as defined by ISO 3166-1 alpha-2

Required string length: 2

Example:

"NY"

rows.task

enum<string>

Common types of AI/ML models and their primary functions:

Text-based models for natural language processing
Vision models for image analysis and generation
Audio models for speech and sound processing
Multimodal models that combine different types of inputs/outputs
Specialized models for specific use cases

Available options:

text-generation,

chat,

text-embedding,

text-classification,

sentiment-analysis,

named-entity-recognition,

question-answering,

summarization,

translation,

image-classification,

object-detection,

image-segmentation,

image-generation,

image-to-text,

text-to-image,

style-transfer,

face-detection,

facial-recognition,

speech-to-text,

text-to-speech,

speaker-identification,

audio-classification,

music-generation,

multimodal-embedding,

multimodal-generation,

visual-question-answering,

recommendation-system,

reinforcement-learning,

anomaly-detection,

time-series-forecasting,

clustering

rows.input_tokens

integer

the number of input (or prompt) tokens

Required range: 0 <= x <= 100000000

Example:

128

rows.input_audio_seconds

number

the duration of audio input in seconds

Required range: 0 <= x <= 100000

Example:

60

rows.output_tokens

integer

the number of output (or completion) tokens

Required range: 0 <= x <= 100000000

Example:

128

rows.input_images

string[]

rows.input_steps

integer

the number of steps to use in the model

Required range: 1 <= x <= 10000

Example:

50

rows.output_images

string[]

a list of output image sizes

rows.output_audio_seconds

number

the duration of audio output in seconds

Required range: 0 <= x <= 100000

Example:

60

rows.output_audio_tokens

integer

the number of audio tokens in the output

Required range: 0 <= x <= 100000000

Example:

2300

rows.output_video_frames

integer

the number of video frames (frame rate x duration)

Required range: 0 <= x <= 100000000

Example:

60

rows.output_video_resolution

integer

the resolution of the video in number of lines (for instance, 1080 for 1080p)

Example:

1080

Response

200

application/json

Impact metrics retrieved successfully

rows

object[]

required

rows.total_impact

object

required

rows.inference_impact

object

rows.training_impact

object

rows.fine_tuning_impact

object

rows.debug

object

rows.debug.model

object

rows.debug.model.id

string

required

Example:

"gpt-4-turbo"

rows.debug.model.aliases

string[]

required

List of aliases for this model; must be globally-unique with id

Example:

["claude-latest", "claude-3-sonnet-current"]

rows.debug.model.number_of_experts

integer

required

Example:

7

rows.debug.model.customer_id

integer

required

ID of the customer who owns this node (visible to admins only)

rows.debug.model.created_at

string

required

rows.debug.model.updated_at

string

required

rows.debug.model.created_by

string

required

ID of the user who created the node (admin or owner only)

rows.debug.model.name

string

Example:

"GPT-4 Turbo"

rows.debug.model.family

string

Example:

"gpt"

rows.debug.model.hugging_face_path

string

Example:

"EleutherAI/gpt-neo-2.7B"

rows.debug.model.benchmark_model_id

string

Example:

"GPTJ-6B"

rows.debug.model.total_params_billions

number

Example:

175

rows.debug.model.params_per_expert_billions

number

Example:

8

rows.debug.model.tensor_parallelism

integer

Example:

1

rows.debug.model.datatype

enum<string>

Available options:

fp8,

fp8-e4m3,

fp8-e5m2,

fp16,

tf32,

fp32,

fp64,

bfloat8,

bfloat16,

bf16,

int4,

int8,

int16,

int32,

int64,

uint4,

uint8,

uint16,

uint32,

uint64

rows.debug.model.task

enum<string>

Common types of AI/ML models and their primary functions:

Text-based models for natural language processing
Vision models for image analysis and generation
Audio models for speech and sound processing
Multimodal models that combine different types of inputs/outputs
Specialized models for specific use cases

Available options:

text-generation,

chat,

text-embedding,

text-classification,

sentiment-analysis,

named-entity-recognition,

question-answering,

summarization,

translation,

image-classification,

object-detection,

image-segmentation,

image-generation,

image-to-text,

text-to-image,

style-transfer,

face-detection,

facial-recognition,

speech-to-text,

text-to-speech,

speaker-identification,

audio-classification,

music-generation,

multimodal-embedding,

multimodal-generation,

visual-question-answering,

recommendation-system,

reinforcement-learning,

anomaly-detection,

time-series-forecasting,

clustering

rows.debug.model.training_usage_energy_kwh

number

Example:

1013.1

rows.debug.model.training_usage_emissions_kgco2e

number

Example:

1013.1

rows.debug.model.training_usage_water_l

number

Example:

1013.1

rows.debug.model.training_embodied_emissions_kgco2e

number

Example:

11013.1

rows.debug.model.training_embodied_water_l

number

Example:

11013.1

rows.debug.model.estimated_use_life_days

number

Example:

1013.1

rows.debug.model.estimated_requests_per_day

number

Example:

1013.1

rows.debug.model.fine_tuned_from_model_id

string

Example:

"llama_31_8b"

rows.debug.hardware_node

object

Create a new node. Note on permissions:

cloud_instance_id and managed_service_id can only be set by admins or users who own those resources
Custom nodes are visible only to their owners
Global nodes are visible to all users
Admins can see and manage all nodes

rows.debug.grid_mix

object

rows.debug.steps

object[]

rows.error

object

has_errors

boolean

required

Example:

false

total_energy_wh

number

Example:

0.13

total_gco2e

number

Example:

0.81

total_mlh2o

number

Example:

1.32

Get status Calculate AI model impact metrics for BigQuery

curl --request POST \
  --url https://aiapi.scope3.com/v1/impact \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "rows": [
    {
      "utc_datetime": "2022-01-01T00:00:00Z",
      "request_duration_ms": 283,
      "processing_duration_ms": 238,
      "request_cost": 0.18,
      "currency": "USD",
      "integration_source": "litellm",
      "environment": "staging",
      "session_id": "<string>",
      "trace_id": "<string>",
      "request_id": "<string>",
      "client_id": "<string>",
      "project_id": "<string>",
      "application_id": "<string>",
      "model_id": "llama_31_8b",
      "model_family": "llama",
      "model_name": "LLaMa v3.1 8B",
      "model_hugging_face_path": "meta/llama31_8b",
      "model_used_id": "llama_31_8b_0125",
      "base_url": "https://openrouter.ai/api/v1/chat/completions",
      "cloud_region": "us-east-1",
      "managed_service_id": "aws-bedrock",
      "cloud_id": "aws",
      "cloud_instance_id": "p4d.24xlarge",
      "node_id": "aws:p4d.24xlarge",
      "datacenter_id": "550e8400-e29b-41d4-a716-446655440000",
      "country": "US",
      "region": "NY",
      "task": "text-generation",
      "input_tokens": 128,
      "input_audio_seconds": 60,
      "output_tokens": 128,
      "input_images": [
        "1024x1024"
      ],
      "input_steps": 50,
      "output_images": [
        "1024x1024"
      ],
      "output_audio_seconds": 60,
      "output_audio_tokens": 2300,
      "output_video_frames": 60,
      "output_video_resolution": 1080
    }
  ]
}'

{
  "rows": [
    {
      "inference_impact": {
        "usage_energy_wh": 0.13,
        "usage_emissions_gco2e": 0.81,
        "usage_water_ml": 1.32,
        "embodied_emissions_gco2e": 0.81,
        "embodied_water_ml": 1.32
      },
      "training_impact": {
        "usage_energy_wh": 0.13,
        "usage_emissions_gco2e": 0.81,
        "usage_water_ml": 1.32,
        "embodied_emissions_gco2e": 0.81,
        "embodied_water_ml": 1.32
      },
      "fine_tuning_impact": {
        "usage_energy_wh": 0.13,
        "usage_emissions_gco2e": 0.81,
        "usage_water_ml": 1.32,
        "embodied_emissions_gco2e": 0.81,
        "embodied_water_ml": 1.32
      },
      "total_impact": {
        "usage_energy_wh": 0.13,
        "usage_emissions_gco2e": 0.81,
        "usage_water_ml": 1.32,
        "embodied_emissions_gco2e": 0.81,
        "embodied_water_ml": 1.32
      },
      "debug": {
        "model": {
          "id": "gpt-4-turbo",
          "aliases": [
            "claude-latest",
            "claude-3-sonnet-current"
          ],
          "name": "GPT-4 Turbo",
          "family": "gpt",
          "hugging_face_path": "EleutherAI/gpt-neo-2.7B",
          "benchmark_model_id": "GPTJ-6B",
          "total_params_billions": 175,
          "number_of_experts": 7,
          "params_per_expert_billions": 8,
          "tensor_parallelism": 1,
          "datatype": "fp8",
          "task": "text-generation",
          "training_usage_energy_kwh": 1013.1,
          "training_usage_emissions_kgco2e": 1013.1,
          "training_usage_water_l": 1013.1,
          "training_embodied_emissions_kgco2e": 11013.1,
          "training_embodied_water_l": 11013.1,
          "estimated_use_life_days": 1013.1,
          "estimated_requests_per_day": 1013.1,
          "fine_tuned_from_model_id": "llama_31_8b",
          "customer_id": 123,
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "created_by": "<string>"
        },
        "hardware_node": {
          "id": "my-custom-node-1",
          "cloud_id": "aws",
          "cloud_instance_id": "a2-highgpu-1g",
          "managed_service_id": "aws-bedrock",
          "gpu_id": "a100_40gb",
          "gpu_count": 8,
          "cpu_count": 2,
          "idle_power_w_ex_gpu": 100,
          "average_utilization_rate": 0.8,
          "embodied_emissions_kgco2e_ex_gpu": 2500,
          "embodied_water_l_ex_gpu": 2500,
          "use_life_years": 5,
          "customer_id": 123,
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "created_by": "<string>"
        },
        "grid_mix": {
          "country": "US",
          "region": "NY",
          "gco2e_per_kwh": 475
        },
        "steps": [
          {
            "description": "<string>",
            "duration_ms": 123,
            "inferences": 123
          }
        ]
      },
      "error": {
        "code": "<string>",
        "message": "<string>",
        "details": {
          "reason": "<string>",
          "field": "<string>"
        }
      }
    }
  ],
  "total_energy_wh": 0.13,
  "total_gco2e": 0.81,
  "total_mlh2o": 1.32,
  "has_errors": false
}

Guides

Integrations

API Reference

Get impact metrics for a task

Authorizations

Query Parameters

Body

Response